# RevKeen — Complete Documentation RevKeen is the billing and payments platform with acquirer-level margin intelligence — built on Elavon and NMI, with no merchant-of-record markup. You see what you actually earn, and you keep more of it. Base URLs: - Production API: https://api.revkeen.com/v2 - Staging API: https://staging-api.revkeen.com/v2 - Dashboard: https://app.revkeen.com - Docs: https://docs.revkeen.com Authentication: send your API key in the `x-api-key` header. Production keys start with `rk_live_*`; staging keys start with `rk_sandbox_*`. --- # RevKeen Documentation Source: https://docs.revkeen.com/docs/ Know what you keep, not just what you earn. The billing and payments platform with acquirer-level margin intelligence — built on Elavon and NMI, with no merchant-of-record markup. # Know what you keep, not just what you earn RevKeen is the only billing platform that shows you your true margin on every transaction — every interchange cost, every scheme fee, every decline — because we run the whole payments stack. Built on Elavon and NMI, with no merchant-of-record layer adding a markup on top. You see what you actually earn, and you keep more of it. ## Why RevKeen - **See your real margin**: Stripe, Polar and Paddle can't show you your true cost of payments — they are the cost, or they add a merchant-of-record markup on top. RevKeen runs on Elavon as acquirer and NMI as gateway, so every fee is visible. Know your net revenue per customer, per product, per transaction — not just your gross. - **You own the merchant relationship**: RevKeen is not a merchant of record. Your customers pay you, not a reseller. You keep direct relationships, direct chargeback handling, and direct brand on every statement descriptor. Global tax compliance is handled through our Quaderno integration — you don't give up VAT and sales tax automation to get control back. - **The full billing suite Polar doesn't have**: Automated dunning with smart retries, customer health scores, wallet credits, Direct Debit (London & Zurich), card-present terminals (PAX A920 Pro), and a branded customer portal. Enterprise-grade billing operations, without enterprise pricing or a procurement cycle. - **Priced for operators, not platforms**: Polar charges 4% + $0.40 as merchant of record. Paddle is 5% + $0.50. RevKeen is 1.7% + £0.10 per transaction plus a flat monthly subscription — roughly 40% cheaper at £10k/month in volume, and the gap widens as you grow. Worked example below. ## How the numbers compare A worked example on **£10,000/month** in revenue across **200 transactions**: | Platform | Model | Processing cost | Subscription | Total/month | | ---------- | ------------------ | ------------------------- | ------------ | ----------- | | **Paddle** | Merchant of record | 5% + $0.50 (~£580) | — | **~£580** | | **Polar** | Merchant of record | 4% + $0.40 (~£480) | — | **~£480** | | **RevKeen (Pro)** | Direct PayFac | 1.7% + £0.10 (~£190) | £119 | **~£309** | At this volume, RevKeen saves roughly **£170/month — over £2,000/year** versus Polar, and close to **£3,300/year** versus Paddle. And because our percentage is lower, every pound of additional revenue you add compounds the saving. > **Note:** RevKeen plans: **Standard** £69/mo (150 txn), **Pro** £119/mo (450 txn), **Unlimited** £199/mo. All plans include the full billing suite, margin intelligence, and the same 1.7% + £0.10 transaction rate. ## What RevKeen handles **Billing automation** — Recurring subscriptions, usage-based metering, one-time invoices, and automated dunning so you collect more revenue with less manual work. **Payments** — Hosted checkout pages, payment links, card-on-file renewals, refunds, voids, Direct Debit, and card-present terminals — all routed through your Elavon merchant account with NMI as the gateway. **Customer operations** — Health scores, a self-service customer portal, wallet credits, and multi-channel notifications (email, SMS, WhatsApp) to keep customers informed and engaged. **Margin intelligence** — True net revenue per transaction, product, and customer. Settlement reconciliation. Fee breakdowns at interchange, scheme, and processor levels. This is the view no other platform can give you. **Integrations** — Connect CRMs, accounting tools (Xero, QuickBooks), practice management systems (PracticeHub, Wodify), tax automation (Quaderno), and custom workflows via webhooks and our REST API. ## Get started in 3 steps ### Create your account Sign up and configure your merchant profile. [Account setup →](/docs/getting-started/account-setup) ### Connect your Elavon merchant account We'll guide you through underwriting and NMI gateway setup so you're ready to process. [Gateway setup →](/docs/getting-started/gateway-setup) ### Collect your first payment Create a product, generate a payment link, and get paid. [First payment →](/docs/getting-started/first-payment) ## Explore by topic - **Getting Started**: Account setup, gateway configuration, and your first payment - **Using RevKeen**: Customers, invoices, subscriptions, products, and the dashboard - **Money**: Payments, refunds, settlements, and financial operations - **Operations**: Billing automation, dunning, notifications, and workflows - **Integrations**: Connect RevKeen with CRMs, accounting tools, and webhooks ## Developer resources - **API Reference**: Complete REST API documentation with request/response examples - **Fundamentals**: Authentication, pagination, idempotency, and error handling - **Webhooks**: Real-time event notifications for your application - **SDKs**: TypeScript, Python, and other client libraries - **CLI**: Command-line tools for managing your RevKeen resources - **MCP**: Model Context Protocol integration for AI assistants ## LLM-friendly documentation Machine-readable documentation for AI assistants and LLM-powered tools: - [`llms.txt`](/llms.txt) — Lightweight index of all documentation pages with titles, URLs, and descriptions - [`llms-full.txt`](/llms-full.txt) — Complete documentation in plain text, suitable for context injection - [`openapi.json`](/api/openapi-spec) — Machine-readable OpenAPI 3.1 specification ## Popular guides - **Developer Quickstart**: Get up and running with the API in minutes - **Handle Webhooks**: Process real-time payment events - **Idempotency**: Safely retry requests without duplicate side effects - **Error Handling**: Understand error codes and handle failures gracefully --- # RevKeen Source: https://docs.revkeen.com/docs/revkeen A transparent Payment Facilitator with built-in margin intelligence, designed for businesses that want to own their revenue stack. # RevKeen A transparent Payment Facilitator with margin intelligence built in. ## What is RevKeen? RevKeen is a billing and payments platform that handles the full lifecycle of getting paid — subscriptions, one-off charges, invoices, checkout links, and in-person terminal transactions — on top of a transparent interchange++ pricing model. Unlike merchant-of-record platforms that bundle processing costs into a marked-up flat rate, RevKeen shows you every fee and every margin, per transaction. Our tagline — **Know What You Keep, Not Just What You Earn** — is the operating principle. Every billing platform shows revenue. Only RevKeen automatically tracks processing fees, gateway costs, and infrastructure expenses so you can see your true margin on every sale. ## Payment models: PSP vs MoR vs PayFac There are three structurally different ways to move money from a customer's card to your bank account. Understanding which model you're using matters more than comparing headline rates — the model dictates what you're liable for, what's hidden from you, and where your margin goes. ### Payment Service Providers (PSPs) Examples: Stripe, Braintree, Adyen, PayPal (for processing). PSPs give you direct access to the card networks through their infrastructure. You are the merchant of record for your own sales, meaning you're responsible for sales tax, VAT, chargeback liability, and regulatory compliance. PSPs typically quote a blended rate (e.g. Stripe at 2.9% + 30p) which absorbs interchange, scheme fees, and their margin into one number. - Direct merchant account in your name - Full control of the customer relationship - Lowest headline fees - You are responsible for tax compliance and chargeback exposure - You cannot see interchange or scheme costs separately — they're blended into the rate - No built-in billing operations (subscriptions, invoicing, dunning) — you integrate those separately ### Merchants of Record (MoRs) Examples: Polar, Paddle, Lemon Squeezy, FastSpring. MoRs legally act as the seller of your products. The transaction is between the customer and the MoR; the MoR then pays you net of their fee. They assume sales tax, VAT, and chargeback liability across global jurisdictions. In exchange, they charge a higher blended rate (typically 4%–6%) with additional surcharges for international cards and subscription payments. - MoR handles sales tax, VAT, and GST globally - Chargeback liability transfers to the MoR - Simple to get started — no merchant underwriting - Highest fees of any model — often 6%–7%+ effective rate on international SaaS - Your customers see the MoR's name on their statement, not yours - Less control over pricing, checkout branding, and customer communications - No visibility into processing costs — everything is bundled into the fee ### Payment Facilitators (PayFacs) Examples: RevKeen, Square, Stripe (Connect Standard), Shopify Payments. PayFacs enable businesses to accept card payments under a master merchant relationship with an acquirer, without each business needing its own direct acquirer contract. The merchant remains the legal seller of record; the PayFac manages underwriting, compliance, and technical integration with the acquirer. PayFacs typically quote interchange++ pricing (passing interchange, scheme fees, and acquirer costs through at cost, with a platform margin separate). - You remain the merchant of record with the customer - Processing costs are visible and pass through at cost - Faster underwriting than a direct acquirer relationship - Lower effective fees than MoRs for most business profiles - You remain responsible for tax compliance (though integrations like Quaderno automate this) - Chargebacks come to you directly — the PayFac helps but doesn't shield you ### Which should you choose? As with most infrastructure decisions, there's no universally correct answer: **Choose a PSP (Stripe, Braintree) if:** - You have engineering resources to build billing, subscriptions, dunning, and customer portal yourself - You want the lowest possible processing fees and will handle tax compliance separately - You already have a direct acquirer relationship and don't need PayFac-style onboarding **Choose an MoR (Polar, Paddle) if:** - Your top priority is eliminating sales tax and VAT compliance work entirely - You're a small software company selling digital goods internationally and don't want to think about tax - You're willing to pay a premium (4%–7%+) for the MoR shield on chargebacks and compliance **Choose RevKeen (PayFac) if:** - You want to own the customer relationship and keep your brand on statements - You want transparent pricing with visibility into processing costs - You need a complete billing platform — subscriptions, invoicing, dunning, margin intelligence, customer portal — without integrating half a dozen tools - You accept that you'll handle tax compliance (with help from integrations like Quaderno) in exchange for materially lower effective fees - You want margin intelligence on every transaction rather than an opaque blended rate ## How RevKeen works ### The transaction flow Every RevKeen transaction flows through four layers. Understanding the flow explains where each fee comes from. 1. **Your customer enters card details** at your checkout (hosted page, embedded form, payment link, invoice, terminal, or API call). 2. **RevKeen tokenises and routes** the payment through our NMI gateway to our acquiring partner. 3. **The acquirer authorises** the transaction with the card issuer's bank through Visa, Mastercard, or the relevant card network. This step generates interchange and scheme fees. 4. **Funds settle** from the acquirer to your bank account, typically next business day for UK merchants. Pass-through processing costs and RevKeen's fee are deducted at settlement. You are the merchant of record throughout. The customer's statement shows your business name. The funds arrive in your account. The tax liability, chargeback exposure, and customer relationship are yours. ### What RevKeen handles - **Billing platform** — Subscriptions, invoices, one-off charges, checkout links, usage-based billing, trials, discounts, plan changes. - **Payment gateway** — Tokenisation, 3-D Secure 2, basic fraud screening (AVS, CVV, velocity), and API access to process transactions. - **Customer operations** — Hosted customer portal, multi-channel notifications (email, SMS, WhatsApp), automated dunning, customer health scores. - **Margin intelligence** — Per-transaction cost tracking, margin analysis by customer, product, or geography. - **Compliance inheritance** — PCI DSS Level 1 scope through our PayFac structure; you never handle raw card numbers. - **Integrations** — Native integrations with Xero, QuickBooks, PracticeHub, Wodify, Quaderno, and custom integrations via webhooks, REST API, MCP server, or CLI. ### What you remain responsible for - **Sales tax, VAT, and GST** — You are the merchant of record. Tax calculation, collection, filing, and remittance are your responsibility. Our [Quaderno integration](/docs/integrations/quaderno) automates calculation and filing across 100+ jurisdictions at a fraction of what an MoR markup would cost. - **Chargeback management** — Disputes come to you. RevKeen provides tools to respond, pre-dispute alerts (Verifi CDRN, Ethoca where enrolled), and dunning automation to reduce disputes — but you make the decisions and incur dispute fees. - **Customer service** — Your customers contact you, not us. RevKeen's customer portal reduces your support load by letting customers self-serve cancellations, payment method updates, and invoice downloads. - **Your products and services** — What you sell, how you price it, how you fulfil it. RevKeen handles the money, not the merchandise. ## Transparency RevKeen is built on a specific conviction: merchants should be able to see every cost that affects their margin. This conviction shapes how the product works. ### Interchange++ pricing, not blended rates Most payment platforms quote a blended rate: one number that absorbs interchange, scheme fees, acquirer margin, and platform margin into a single headline figure. This is simpler to communicate, but it hides the actual cost structure from the merchant. You can't tell what's regulated (and therefore fixed), what's negotiable, or what the platform is marking up. RevKeen quotes **1.7% + £0.10** as our platform fee — covering the billing platform, payment gateway, and basic fraud screening. Interchange, scheme fees, and acquirer costs pass through at cost, visible on your settlement statement at the exact percentage our acquirer charges us. See the [Fees](./fees) page for a complete reference. ### Margin intelligence (rolling out Q2 2026) Configure the interchange, scheme fee, and acquirer cost rates from your acquirer's pricing schedule — with sensible defaults based on standard UK and EU published schedules to start. RevKeen then applies those rates to every transaction to compute your estimated margin, broken down by card type, geography, and product. Estimates reconcile against your monthly settlement statement over time. No merchant-of-record platform can offer this at any price, because MoRs sit on top of blended PSPs and never see the underlying cost stack themselves. ## Where RevKeen operates RevKeen Limited is incorporated and regulated in Jersey, Channel Islands. We process payments through our acquiring partner on a global card network reach — which means customers anywhere in the world can pay a RevKeen merchant in a supported currency. Merchant underwriting is currently available for businesses based in the UK, Channel Islands, Ireland, and select EEA countries. For complete coverage detail, see [Supported Countries](./supported-countries). ## What you can and cannot sell RevKeen serves a broad range of businesses — SaaS, digital products, professional services, healthcare, fitness, wellness, coaching, and coworking — but card network rules and regulated-industry restrictions apply. Some categories are prohibited; others require enhanced underwriting review. For the complete policy, see [Acceptable Use](./acceptable-use). ## Frequently asked questions No. RevKeen is a Payment Facilitator. You remain the merchant of record for your own sales — the customer relationship, the tax liability, and the chargeback exposure are all yours. This is the opposite of platforms like Polar and Paddle, which legally act as the seller and shield you from those responsibilities in exchange for a higher fee. RevKeen processes payments through a partnership with Elavon, one of the world's largest acquirers. Your merchant account is underwritten by our acquirer under our PayFac sponsorship, which means faster onboarding than a direct acquirer relationship while maintaining the same regulatory framework. **1.7% + £0.10 per successful card transaction**, plus a monthly subscription (£69 Standard / £119 Pro / £199 Unlimited) and pass-through interchange, scheme fees, and acquirer costs. For a typical UK consumer debit e-commerce transaction, your total all-in cost is roughly 2.2%–2.8%. See the [Fees](./fees) page for the full reference. Stripe and RevKeen operate at different levels of the stack. Stripe is a PSP that gives you access to the card networks; RevKeen is a PayFac and billing platform built on our own acquiring partner. Stripe's headline rate (2.9% + 30p) is comparable to RevKeen's all-in cost for domestic transactions, but Stripe doesn't include subscription billing, dunning, customer portal, or margin intelligence — you integrate Stripe Billing (£620/month minimum contract + 0.7% of billing volume) or build those yourself. For most subscription and service businesses, RevKeen is cheaper all-in and ships with the billing operations already built. Polar and Paddle are merchants of record charging 4%–5% headline rates with additional surcharges for international cards, subscriptions, and currency conversion. Effective rates often reach 6%–7% for international SaaS. RevKeen's PayFac model puts the effective rate around 2.2%–2.8% for domestic and 3.5%–4.5% for international transactions. The tradeoff: you remain responsible for tax compliance (which Quaderno automates), and you handle chargebacks directly. Yes. RevKeen is a unified billing platform — subscriptions, one-time payments, invoices, checkout links, usage-based billing, and in-person terminal transactions all work in the same account at the same 1.7% + £0.10 rate. If your business is small enough that the sales tax and VAT burden dominates your operational cost, or if you're selling into jurisdictions where compliance is infeasible without MoR cover, then an MoR like Polar or Paddle may be right for you despite the higher fees. We're not the right fit in that case. For everyone else — any subscription business, service business, or SaaS processing above ~£5k/month — RevKeen's economics and ownership model consistently win. RevKeen is not a merchant of record, not a bank, not an accounting tool, not a website builder, and not a booking system. We process payments and run billing operations. For accounting, integrate with Xero or QuickBooks. For bookings, integrate with PracticeHub or Wodify. For tax compliance, use our Quaderno integration. For everything else, use the REST API, SDKs, MCP server, or webhooks to connect RevKeen to your own stack. ## Learn more - [Fees](./fees) — complete pricing reference, including interchange++ pass-through and fee calculation examples - [Supported Countries](./supported-countries) — merchant and customer coverage, settlement currencies - [Acceptable Use](./acceptable-use) — what you can and cannot sell through RevKeen - [Getting Started](/docs/getting-started) — account setup, gateway configuration, and first payment --- # Acceptable Use Source: https://docs.revkeen.com/docs/revkeen/acceptable-use What you can and cannot sell through RevKeen, including prohibited activities, restricted business categories, and enhanced review requirements. # Acceptable Use This Acceptable Use Policy applies to all services provided by RevKeen Limited (RevKeen) and all products or services sold by merchants using RevKeen. You are responsible for complying with all applicable laws in all your actions related to using RevKeen, regardless of the purpose of use. Failure to comply with this Acceptable Use Policy may result in immediate suspension or termination of your RevKeen account, forfeiture of settled funds held pending reconciliation, and reporting to the card networks' MATCH file and other regulatory bodies where required. Capitalised terms used but not defined here have the meanings given in the [RevKeen Master Services Agreement](/legal/master-services-agreement). ## Prohibited activities You may not use RevKeen for activities that: 1. Violate any law, statute, ordinance, or regulation in any applicable jurisdiction. 2. Violate the rules or regulations of Visa, Mastercard, American Express, Discover, JCB, Diners Club, UnionPay, or any other card brand network. 3. Relate to transactions involving: - Items that encourage, promote, facilitate, or instruct others to engage in illegal activity. - Stolen goods including digital and virtual goods. - The promotion of hate, violence, racial or other forms of intolerance that is discriminatory, or the financial exploitation of a crime. - Items that infringe or violate any copyright, trademark, right of publicity or privacy, or any other proprietary right under the laws of any jurisdiction. 4. Involve transactions that display the personal information of third parties in violation of applicable law. 5. Involve any activity that requires pre-approval without having obtained that approval. You may not: 1. Reverse engineer, disassemble, decompile, decode, adapt, or otherwise attempt to derive or gain access to the source code of RevKeen's services, other than open-source components released under their respective licences. 2. Bypass or breach any security device or protection used by RevKeen, or access or use the services other than by an authorised user through their own valid access credentials. 3. Input, upload, transmit, or otherwise provide to or through RevKeen any information or materials that are unlawful or injurious, including harmful code or malware. 4. Damage, destroy, disrupt, disable, impair, interfere with, or otherwise impede or harm RevKeen's services, systems, or provision of services to any third party. 5. Remove, delete, alter, or obscure any trademarks, warranties, disclaimers, or any copyright, trademark, patent, or intellectual property notices from RevKeen's services. 6. Access or use RevKeen in any manner or for any purpose that infringes, misappropriates, or otherwise violates any intellectual property right or other right of any third party, or that violates any applicable law. 7. Access or use RevKeen for purposes of competitive analysis, the development of a competing software service or product, or any other purpose that is to RevKeen's detriment or commercial disadvantage. 8. Access or use RevKeen in, or in association with, the design, construction, maintenance, or operation of any hazardous environments, systems, or applications, including safety-critical applications where service failure could lead to personal injury or severe property damage. 9. Use RevKeen for the benefit of any individual, organisation, or country identified on the UK HM Treasury consolidated sanctions list, the US OFAC Specially Designated Nationals list, the EU consolidated financial sanctions list, or for any third parties unaffiliated with your business. 10. Otherwise access or use RevKeen beyond the scope of the authorisation granted under the Master Services Agreement. ## Acceptable products and services RevKeen is designed to support a broad range of businesses, including both digital and physical goods, services, and hybrid models. Acceptable categories include but are not limited to: **Software and SaaS** - Subscription software and services (B2B and B2C) - One-time software licences - Usage-based software billing - API access and developer tools **Digital products** - eBooks, templates, courses, design assets - Fonts, icons, photographs, videos, and audio files - Private content subscriptions (excluding adult content) - License keys and digital downloads **Professional and personal services** - Healthcare practitioners (doctors, dentists, physiotherapists, psychologists, nutritionists) - Wellness services (massage, acupuncture, osteopathy, sauna and wellness centres) - Fitness services (gyms, personal trainers, group classes, specialised fitness) - Coaching services (life, executive, career) - Beauty and personal care (salons, spas) - Coworking and shared workspace memberships - Professional services (consulting, legal, accounting — in line with regulatory requirements of the respective jurisdiction) **Physical goods and retail** - Physical products sold online with standard shipping - In-person retail via our PAX A920 Pro card-present terminal integration - Hospitality (cafes, restaurants, hotels with appropriate terminal or online configuration) - Event tickets (subject to chargeback monitoring, see Restricted Businesses below) **Nonprofits and charities** - Registered charities and nonprofit organisations - Donation and fundraising activities (subject to regulatory compliance in the collecting jurisdiction) If you are unsure whether your business is supported, [contact support](/docs/support) before signing up. We can confirm eligibility and, where needed, guide you through enhanced underwriting. ## Prohibited products and services You may not use RevKeen to sell any product or service that: 1. Violates any rules or regulations of the card brand networks (Visa, Mastercard, Amex, Discover, JCB, Diners Club, UnionPay). 2. Violates any law or government regulation in the merchant's or customer's jurisdiction. 3. Involves fraudulent, deceptive, unfair, abusive, or predatory practices. 4. Is marketed through outbound telemarketing or unsolicited bulk communications. 5. Threatens reputational damage to RevKeen, our acquiring partner, or any card brand network. 6. Results in or causes a significant risk of chargebacks, fines, damages, or harm and liability. 7. Engages in, encourages, promotes, or celebrates violence or physical harm to persons or property, or toward any group based on race, religion, disability, gender, sexual orientation, national origin, or any other immutable characteristic. The following business categories are **explicitly prohibited** on RevKeen. This list is not exhaustive, and RevKeen reserves the right to add to it at any time at our sole discretion. Accounts accepting payments from prohibited categories may be suspended or terminated: 1. **Adult content and services** — Pornography, OnlyFans-related services, adult AI-generated content, adult chat services, adult dating services, escort services. 2. **Gambling, betting, and gaming of chance** — Casinos, sports betting, online poker, lottery services, loot boxes, mystery boxes, skill games with cash payouts. 3. **Illegal or age-restricted products** — Drugs, cannabis and cannabis-derivative products (other than where explicitly licensed), alcohol sold without age verification, tobacco products, vaping products, fireworks, weapons or ammunition. 4. **Cryptocurrencies and blockchain financial products** — Crypto-asset exchanges, trading platforms, NFT marketplaces, crypto wallet services, initial coin offerings. 5. **Financial trading and advisory services** — Trading bots, financial signals platforms, investment advisory services without FCA or equivalent regulatory authorisation, Forex platforms, binary options. 6. **"Get rich" schemes and pyramid marketing** — Multi-level marketing schemes, guaranteed-return investment programmes, matrix schemes. 7. **Services intended for or advertised to minors** — Services where the primary user is under 13 (or under 16 in jurisdictions with higher age limits under data protection law) without verified parental consent mechanisms. 8. **Pseudo-scientific services** — Clairvoyance, fortune-telling, horoscopes, psychic readings, tarot services (when primary offering). 9. **Medical and health advice without licensed practitioners** — Unlicensed health advice platforms, miracle cures, unverified medical claims. 10. **Government services** — Services purporting to be affiliated with any government body without authorisation. 11. **Cheating products** — Game cheats, exam cheats, certification fraud, macros and hacks for online services. 12. **Circumvention services** — Services designed to bypass paywalls, DRM, terms of service of other platforms, or IP restrictions. 13. **IPTV services** — Unlicensed streaming of television or film content; IPTV subscription services; IPTV hardware. 14. **Malware, viruses, spyware** — Any product that damages, surveils, or compromises user systems without consent. 15. **API and IP cloaking services** — Services that facilitate impersonation or misrepresentation. 16. **Third-party trademark removal services** — Products that remove or obscure legitimate trademarks. 17. **eSIM and unauthorised telecommunications services** — Services that resell or facilitate unauthorised SIM cards or telecommunications access. 18. **Third-party content downloaders** — YouTube, Instagram, TikTok, Snapchat, or similar content-downloader services that violate the source platform's terms of service. 19. **Face swap, deep fake, and synthetic media tools** — Tools that enable identity misrepresentation, including voice cloning services without consent mechanisms. 20. **Fake reviews, testimonials, or social proof platforms** — Services that generate or inflate fake reviews, followers, or social engagement. 21. **Data broker and OSINT platforms** — Services that aggregate, resell, or expose personal data about individuals from public or leaked sources. 22. **Unauthorised software licence resale** — Resale or redistribution of software licences without authorisation from the original publisher. 23. **Counterfeit goods** — Counterfeit physical goods, replica products sold as authentic, or goods that infringe on third-party intellectual property. 24. **Standardised test preparation with real exam questions** — Platforms reselling real or past exam questions for IELTS, SAT, GMAT, GRE, or similar due to copyright infringement and regulatory risk. 25. **Direct marketing, lead generation, and unsolicited outreach services** — Bulk SMS platforms, cold-email automation, automated outreach tools (though CRMs and marketing automation for your own business are permitted). RevKeen reserves the right to refuse service to any business at our sole discretion, including for categories not explicitly listed above. ## Restricted businesses (enhanced review) The following categories are supported but require enhanced underwriting review before approval. We may request additional business documentation, proof of licensure, or ongoing monitoring: - **Travel services** — Flight bookings, hotel bookings, travel agencies (subject to IATA or equivalent industry licensing where applicable) - **Event ticket sales** — Concerts, sports, theatre (subject to chargeback rate monitoring) - **Pre-orders and crowdfunding** — Businesses that collect payment before fulfilment must demonstrate a credible fulfilment plan - **Subscription boxes** — Physical goods delivered on a subscription cadence - **High-ticket coaching programmes** — Coaching services sold at over £5,000 per contract - **Directories and job boards** — Platforms that charge for listings or applications - **Paid waitlists and access programmes** — Services charging before delivering primary value - **VPN services** — Legitimate privacy tools subject to enhanced review - **eBook and digital course platforms** — Subject to review for content and IP compliance - **Marketing and advertising services** — Digital marketing agencies (excluded if primary offering is unsolicited outreach) - **Pre-licensed industries** — Regulated industries such as legal services, medical services, financial advice (where FCA-authorised), insurance brokerage, and accountancy — subject to proof of active licensure in the operating jurisdiction ## Categories requiring close review The following categories require close review during onboarding and ongoing monitoring. Approval is subject to the specific nature of the offering and your business history: - **AI content generation tools** (text, image, video, voice) — Subject to review for IP, adult content, deepfake, and misinformation risk - **Marketing and outreach tools** — Subject to review that outreach is consent-based, not unsolicited - **Resume, hiring, and exam preparation tools** — Subject to review of testimonials, claims, and source material - **Spiritual and astrology services** — Supported if not presented as scientific fact or used to make investment or health claims - **Audio, music, and chatbot generators** — Supported without voice cloning, NSFW content, IP infringement, or fake claims - **VPS, VDS, and hosting services** — Supported for legitimate hosting; excluded for hosting of prohibited content - **Cryptocurrency-adjacent services** — Tax tools for crypto holders, educational content, analytics platforms (but not exchanges, custody, or trading services) ## Chargebacks and monitoring Card networks impose monitoring programmes for merchants with elevated chargeback rates: | Programme | Threshold | Consequence | | --------- | --------- | ----------- | | Visa Dispute Monitoring Program (VDMP) | 0.9% chargeback rate or higher | Monthly fines up to $25,000; remediation plan required | | Visa Fraud Monitoring Program (VFMP) | 0.9% fraud rate or higher | Monthly fines; potential processing restrictions | | Mastercard Excessive Chargeback Programme (ECP) | 1.0% chargeback rate or higher | Assessment fees; potential processing restrictions | Because your merchant account is in your name under RevKeen's PayFac sponsorship, these monitoring programmes apply directly to your business. Sustained chargeback rates above scheme thresholds may result in account suspension or termination, independent of other AUP compliance. See [Disputes](/docs/money/disputes) for operational guidance on managing chargeback exposure. ## MATCH and Terminated Merchant File If RevKeen terminates your merchant account for cause — including but not limited to fraud, excessive chargebacks, or AUP violations — you may be reported to the Mastercard Alert to Control High-Risk Merchants (MATCH) file and the Visa Terminated Merchant File (TMF). Being listed on MATCH or TMF typically results in an inability to open a merchant account with any processor for five years. Termination for cause decisions are made at RevKeen's sole discretion based on evidence of AUP violations, chargeback monitoring programme breaches, fraud indicators, or failure to respond to underwriting or compliance requests. ## Changes to this policy This Acceptable Use Policy may be updated as card network rules, regulations, or RevKeen's risk policies evolve. Material changes are announced by email to all merchants at least 30 days before the effective date, unless a shorter notice period is required by card network rules or regulatory obligations. | Date | Change | | ---- | ------ | | 2026-04-20 | Initial publication. | ## Questions and clarifications If you are unsure whether your business is acceptable under this policy, [contact support](/docs/support) **before** signing up. We can confirm eligibility and, where needed, guide you through enhanced underwriting. Ambiguity is safer to resolve before processing begins than after. For technical guidance on dispute and chargeback handling, see [Disputes](/docs/money/disputes). --- # Fees Source: https://docs.revkeen.com/docs/revkeen/fees Complete pricing reference for RevKeen — platform fees, interchange++ pass-through, subscription plans, and worked examples. # Fees RevKeen uses interchange++ pricing. This means you see every cost component separately — interchange, scheme fees, acquirer costs, and RevKeen's platform fee — rather than a single blended rate that hides the actual cost structure. ## Fee components Every card transaction has four cost layers. Three are pass-through (you pay exactly what we're charged); one is RevKeen's platform fee. | Component | Who sets it | Typical range (UK domestic debit) | Pass-through? | | --------- | ----------- | --------------------------------- | ------------- | | **Interchange** | Card issuer (regulated by IFR in UK/EEA) | 0.20% | Yes | | **Scheme fees** | Visa / Mastercard | 0.02%–0.05% | Yes | | **Acquirer margin** | Elavon (our acquiring partner) | 0.10%–0.30% | Yes | | **RevKeen platform fee** | RevKeen | **1.7% + £0.10** | No — this is our fee | ### What "pass-through" means Pass-through fees are charged to RevKeen by the card networks and our acquirer. We pass them to you at the exact rate we're charged — no markup, no rounding, no bundling. You can verify these against your settlement statement. ### RevKeen platform fee: 1.7% + £0.10 This covers the billing platform (subscriptions, invoicing, dunning, customer portal, checkout, usage-based billing), payment gateway (tokenisation, 3DS2, fraud screening), margin intelligence, notifications (email, SMS, WhatsApp), and API/webhook/MCP access. The rate is the same on all plans and all transaction types. ## Subscription plans RevKeen offers three plans. The transaction fee (1.7% + £0.10) is the same on all plans — the subscription determines your included transaction and invoice volume, plus feature access. | | **Standard** | **Pro** | **Unlimited** | |---|:---:|:---:|:---:| | **Monthly fee** | £69 | £119 | £199 | | **Transactions included** | 150/month | 450/month | Unlimited | | **Invoices included** | 10/month | 100/month | Unlimited | | **Dashboard** | Basic | Full | Full | | **Reporting** | Basic | Advanced | Advanced | | **WhatsApp notifications** | -- | Yes | Yes | | **AI Inbox Pro** | -- | -- | Yes | No setup fees. No contracts. Cancel anytime. See [revkeen.com/pricing](https://revkeen.com/pricing) for full details. ### Overage If you exceed the included transaction or invoice count on Standard or Pro, each additional transaction is charged at the standard 1.7% + £0.10 rate. There is no punitive overage fee — you pay the same per-transaction rate; the subscription just determines your included volume. ## Worked examples ### Example 1: UK consumer debit card, £100 sale | Component | Rate | Amount | | --------- | ---- | ------ | | Interchange (UK consumer debit, regulated) | 0.20% | £0.20 | | Scheme fee (Visa domestic) | 0.03% | £0.03 | | Acquirer margin | 0.15% | £0.15 | | **RevKeen platform fee** | **1.7% + £0.10** | **£1.80** | | **Total cost** | | **£2.18** | | **Effective rate** | | **2.18%** | | **You receive** | | **£97.82** | ### Example 2: UK consumer credit card, £100 sale | Component | Rate | Amount | | --------- | ---- | ------ | | Interchange (UK consumer credit, regulated) | 0.30% | £0.30 | | Scheme fee (Mastercard domestic) | 0.04% | £0.04 | | Acquirer margin | 0.15% | £0.15 | | **RevKeen platform fee** | **1.7% + £0.10** | **£1.80** | | **Total cost** | | **£2.29** | | **Effective rate** | | **2.29%** | | **You receive** | | **£97.71** | ### Example 3: EEA consumer debit card, €100 sale to UK merchant | Component | Rate | Amount | | --------- | ---- | ------ | | Interchange (EEA consumer debit, regulated) | 0.20% | €0.20 | | Scheme fee (Visa intra-EEA) | 0.05% | €0.05 | | Acquirer margin (cross-border) | 0.25% | €0.25 | | **RevKeen platform fee** | **1.7% + £0.10** | **€1.80** | | **Total cost** | | **€2.30** | | **Effective rate** | | **2.30%** | ### Example 4: US commercial credit card, $500 sale | Component | Rate | Amount | | --------- | ---- | ------ | | Interchange (US commercial, unregulated) | 2.30% | $11.50 | | Scheme fee (Visa international) | 0.10% | $0.50 | | Acquirer margin (international) | 0.35% | $1.75 | | **RevKeen platform fee** | **1.7% + £0.10** | **$8.60** | | **Total cost** | | **$22.35** | | **Effective rate** | | **4.47%** | This example illustrates why interchange++ is more transparent than blended pricing. A platform quoting "2.9% + 30c" would charge $14.80 on this transaction — but the actual interchange alone is $11.50. The blended-rate platform is making $3.30 ($14.80 minus $11.50) on top of the interchange they'd never show you. With RevKeen, you see every component. ## Interchange reference Interchange rates are set by the card networks and regulated by the Interchange Fee Regulation (IFR) in the UK and EEA. The most common rates: ### UK/EEA regulated rates (consumer cards) | Card type | Interchange cap | | --------- | --------------- | | Consumer debit (in-person and online) | 0.20% | | Consumer credit (in-person and online) | 0.30% | ### Unregulated rates (commercial / international) | Card type | Typical range | | --------- | ------------- | | UK/EEA commercial debit | 1.05%–1.50% | | UK/EEA commercial credit | 1.30%–2.50% | | US consumer credit | 1.50%–2.40% | | US commercial credit | 2.00%–2.95% | | International consumer (non-EEA) | 1.15%–1.85% | | International commercial (non-EEA) | 2.00%–3.00% | These are indicative ranges. Actual interchange varies by card issuer, card programme, merchant category code (MCC), and transaction type (card-present vs card-not-present). RevKeen passes through the exact rate charged by our acquirer. ## Comparison with other platforms | Platform | Model | Headline rate | Effective rate (UK domestic debit, £100) | Effective rate (US commercial credit, $500) | | -------- | ----- | ------------- | ---------------------------------------- | ------------------------------------------- | | **RevKeen** | PayFac (IC++) | 1.7% + £0.10 + IC++ | ~2.2% | ~4.5% | | **Stripe** | PSP (blended) | 2.9% + 30p | ~3.2% | ~3.2% | | **Paddle** | MoR (blended) | 5% + 50c | ~5.5% | ~5.5% | | **Polar** | MoR (blended) | 4% + 40c | ~4.4% | ~4.4% | Key insight: blended-rate platforms charge the same percentage regardless of the underlying interchange. For low-interchange transactions (UK/EEA regulated consumer cards), they capture the difference as hidden margin. For high-interchange transactions (US commercial), their blended rate may actually be close to or below cost — which is why they add surcharges for "international" or "premium" cards. RevKeen's interchange++ model means you pay less on low-interchange transactions (where blended platforms profit most) and more on high-interchange transactions (where blended platforms lose money and add surcharges). ## How fees are deducted Fees are deducted from each settlement before funds reach your bank account: 1. Customer pays £100 2. Interchange + scheme fees + acquirer margin are deducted at settlement (pass-through) 3. RevKeen platform fee (1.7% + £0.10) is deducted at settlement 4. Net amount is included in your next payout You can see the fee breakdown for every transaction in the [Income](/docs/money/income) dashboard. Aggregate fee trends are visible in [Analytics](/docs/money/analytics). ## Refund fees When you issue a refund: - The **full amount** is returned to the customer - The **original interchange and scheme fees** are typically not refunded by the card networks - RevKeen does not charge an additional fee for processing refunds - **Voids** (same-day reversals before settlement) avoid interchange costs entirely because the transaction is cancelled before fees are assessed This means refunds cost you the original processing fees. For high-value refunds, consider voiding instead of refunding where timing permits. ## Chargeback fees When a customer files a dispute (chargeback): - The **disputed amount** is immediately held from your balance - A **chargeback fee** (typically £15–25) is charged by the acquiring bank - If you **win** the dispute, the disputed amount is returned, but the chargeback fee usually is not - If you **lose**, both the amount and fee are permanent See [Disputes](/docs/money/disputes) for how to respond to and prevent chargebacks. ## Direct Debit fees Direct Debit transactions (BACS and SEPA) are priced separately from card transactions: | Rail | Fee | | ---- | --- | | BACS Direct Debit (UK) | £0.50 per collection | | SEPA Core Direct Debit | €0.50 per collection | | SEPA B2B Direct Debit | €0.75 per collection | Direct Debit fees are charged by our partner [London & Zurich](https://londonandzurich.co.uk/) and passed through at cost. There is no additional RevKeen markup on Direct Debit collections. ## What is not charged RevKeen does not charge: - Setup fees - Cancellation fees - PCI compliance fees - Monthly minimum fees - Batch processing fees - FX conversion margin (card network interbank rate applies) - API call fees - Webhook delivery fees - Customer portal hosting fees ## Viewing your fees | View | Where | | ---- | ----- | | Per-transaction breakdown | Open any transaction in [Income](/docs/money/income) | | Per-payout summary | Open any payout in [Payouts](/docs/money/payouts) | | Fee trends over time | [Analytics](/docs/money/analytics) dashboard | | Margin by customer/product/geography | Margin Intelligence (rolling out Q2 2026) | --- # Supported Countries Source: https://docs.revkeen.com/docs/revkeen/supported-countries Where RevKeen operates — merchant underwriting coverage, customer payment acceptance, and settlement currencies. # Supported Countries RevKeen operates across three distinct coverage layers: **where you can have a merchant account**, **where your customers can pay you**, and **what currencies we settle in**. Each layer has different rules and rollout schedules. ## Merchant underwriting Countries where a business can sign up as a RevKeen merchant, subject to standard underwriting. ### Currently supported | Country / region | Status | Notes | | ----------------------------------- | ----------- | ------------------------------------------------------ | | United Kingdom | Live | Full support including BACS Direct Debit | | Jersey (Channel Islands) | Live | RevKeen's home jurisdiction | | Guernsey, Isle of Man | Live | Full support | | Ireland | Live | Full support including SEPA Direct Debit | ### Rolling out in 2026 | Country / region | Status | Expected availability | | ----------------------------------- | -------------- | --------------------- | | Netherlands, Germany, France, Spain, Italy | In progress | Q3 2026 | | Belgium, Austria, Luxembourg, Portugal, Finland | In progress | Q3 2026 | | Denmark, Sweden, Norway | Planned | Q4 2026 | | Switzerland | Planned | Q4 2026 | ### Expansion requests If your country is not listed and you want to become a RevKeen merchant, [contact sales](/docs/support) with your business details, expected monthly volume, and customer geography. We expand underwriting coverage based on aggregate demand and regulatory feasibility — your request helps inform our roadmap. ## Customer payment acceptance RevKeen merchants can accept payments from customers anywhere in the world where their cards are issued. The card networks (Visa, Mastercard, Amex) operate globally, so customer-side geography is rarely a constraint. ### Fully supported Cards issued in any country where the issuing bank participates in Visa, Mastercard, Amex, Discover, JCB, Diners, or UnionPay networks can be processed through RevKeen. This covers over 200 countries and territories. ### Enhanced fraud screening Transactions from the following regions automatically trigger enhanced fraud screening (additional AVS, CVV, velocity, and device-fingerprinting checks). This does not change the processing fee or merchant experience, but may result in elevated decline rates for prospective customers with limited transaction history: - Countries on the OFAC Specially Designated Nationals list (transactions blocked) - Countries subject to UK HM Treasury financial sanctions (transactions blocked) - High-risk jurisdictions per the Financial Action Task Force (FATF) grey and black lists (enhanced screening) - Countries with historically elevated chargeback rates (enhanced screening, may require merchant pre-approval) ### Blocked countries Transactions originating from the following countries are not processed regardless of merchant location, in line with international sanctions and card network rules: - Cuba - Iran - North Korea - Syria - Russia (subject to ongoing sanctions, currently blocked for most transaction types) - Crimea, Donetsk, and Luhansk regions - Any country added to OFAC Specially Designated Nationals list ## Settlement currencies Currencies in which RevKeen can settle funds to your nominated bank account: | Currency | Code | Supported merchant jurisdictions | | -------- | ---- | -------------------------------- | | British Pound | GBP | All current merchant countries | | Euro | EUR | EEA merchants and UK merchants with EUR account | | US Dollar | USD | All current merchant countries with USD account | ### Multi-currency acceptance RevKeen accepts payments in 135+ currencies at checkout. Customer-facing currencies can be configured per-product or per-market. Currency conversion from the customer's currency to your settlement currency happens at the card network interbank rate at the time of capture — RevKeen does not add an FX margin. For comparison, Paddle and PayPal typically add a 2%–3% FX margin on currency conversion. Polar passes through Stripe's FX fees of 0.25%–1% depending on destination currency. ## Supported Direct Debit rails | Rail | Coverage | Notes | | --------------------- | ----------------------------------- | --------------------------------------------- | | UK BACS Direct Debit | UK merchants collecting from UK customers | 3 working days; 3-day reversal window | | SEPA Core Direct Debit | EEA merchants collecting from EEA customers | 2 business days; 8-week reversal window | | SEPA B2B Direct Debit | EEA merchants collecting from EEA business customers | 2 business days; irreversible | Direct Debit is handled through our partner [London & Zurich](https://londonandzurich.co.uk/). See [Direct Debit documentation](/docs/payments/direct-debit) for operational detail. ## Supported card networks | Network | Merchant acceptance | Customer regions | | ----------- | ------------------- | --------------------------------------------- | | Visa | All merchants | Global | | Mastercard | All merchants | Global | | American Express | All merchants | Global (some merchant categories require Amex-specific underwriting) | | Discover | All merchants | Primarily US, Canada, China, Japan | | JCB | All merchants | Primarily Japan, Asia-Pacific | | Diners Club | All merchants | Global | | UnionPay | All merchants | Primarily China and Asia-Pacific | Local payment methods (SEPA, BACS, Open Banking via fire.com, Apple Pay, Google Pay) are also supported depending on the customer's region and your merchant configuration. ## Regulatory status - **RevKeen Limited** is incorporated in Jersey, Channel Islands. - Regulated as a Payment Facilitator under Jersey Financial Services Commission (JFSC). - PCI DSS Level 1 certified through our PayFac scope inheritance. - Our acquiring partner is FCA-regulated in the UK with equivalent regulatory standing in operating EEA markets. ## Questions? Coverage rules change as we expand. For the most current status on a specific market — or to request coverage for a country not listed — [contact support](/docs/support). --- # Introduction Source: https://docs.revkeen.com/docs/getting-started Get up and running with RevKeen -- the billing platform built for margin visibility RevKeen is a billing and payments platform that gives you full visibility into your margins. Process payments, manage subscriptions, send invoices, and understand exactly what you keep after every transaction. ## Choose Your Path - **I'm a business owner** (/docs/for-businesses): Set up billing, accept payments, and track margins -- no code required. - **I'm a developer** (/docs/developers): Integrate the API, handle webhooks, use official SDKs, and build custom billing flows. ## Get Started in 3 Steps 1. **Create your account** -- [Sign up](https://app.revkeen.com) and complete the onboarding wizard. Takes about 10 minutes. [Account setup guide](/docs/getting-started/account-setup) 2. **Connect your payment gateway** -- Link your NMI gateway credentials so RevKeen can process payments. [Gateway setup guide](/docs/getting-started/gateway-setup) 3. **Accept your first payment** -- Create a product, generate a checkout link, and test the full payment flow. [First payment guide](/docs/getting-started/first-payment) ## What RevKeen Does | Capability | Description | |-----------|-------------| | **Payments** | Accept card payments online and in-person via terminal | | **Subscriptions** | Recurring billing with trials, plan changes, and proration | | **Invoices** | Automatic and manual invoicing with PDF generation | | **Usage billing** | Meter-based pricing with graduated, volume, and package tiers | | **Dunning** | Smart payment retry with decline classification | | **Checkout** | Hosted checkout pages with Apple Pay and Google Pay | | **Customer portal** | Self-service billing management for your customers | | **Terminal** | In-person payments via PAX A920 terminals | | **Margin visibility** | See processing costs, gateway fees, and net revenue per transaction | | **Integrations** | PracticeHub, Xero, QuickBooks, Slack, and more | ## Pricing RevKeen charges **1.7% + 10p per transaction** on top of gateway fees. Three platform plans available: Standard (£69/mo), Pro (£119/mo), Unlimited (£199/mo). No hidden costs, no contracts. See [How Fees Work](/docs/money/how-fees-work) for the full breakdown. ## Core Concepts Before diving in, review the [core concepts](/docs/getting-started/core-concepts) to understand how Products, Prices, Customers, Invoices, and Subscriptions relate to each other. --- # Account Setup Source: https://docs.revkeen.com/docs/getting-started/account-setup Create and configure your RevKeen merchant account - How to create your RevKeen account with a magic link - How to complete the 6-step guided onboarding - What happens during account review - How to access sandbox mode during your free trial RevKeen is built for businesses that need reliable payment infrastructure without the usual onboarding headaches. Our guided setup walks you through everything step by step, with auto-save at every stage so you never lose your progress. Most merchants complete the full onboarding in under 15 minutes. Once submitted, our team reviews your application and handles the payment gateway setup on your behalf -- you will not need to navigate complex provider portals or manage technical configurations yourself. > **Note:** You get a **14-day free trial** with full sandbox access from the moment you sign up. Start exploring the dashboard, create test products, and run test transactions while your account is being reviewed. ## How It Works 1. **Sign Up and Onboard** -- Create your account with a magic link -- no passwords to remember. Complete the 6-step guided setup at your own pace. 2. **We Handle the Rest** -- Our ops team reviews your application, provisions your payment gateway, and configures everything for you. You will receive an application reference to track progress. 3. **Go Live** -- Once approved and provisioned, your live payment gateway is activated. Start accepting real payments with cards, Apple Pay, and Google Pay. ## What You Will Need Have the following ready before you start. If you do not have everything yet, you can still begin -- the onboarding auto-saves your progress so you can come back anytime. - A valid email address (we use magic links -- no passwords needed) - Your business name and trading name (if different) - A support email and website URL - Your company logo (PNG or SVG, minimum 200px) - Basic information about your products and how you plan to use RevKeen - Contact details for your primary point of contact ## The 6-Step Guided Onboarding Every step auto-saves as you go. You can leave and come back at any time -- your progress is always preserved. The entire process typically takes 10-15 minutes. ### Step 1: Organization Details Tell us about your business. This is the foundation of your RevKeen account. - **Organization Name** -- Your legal business name - **Trading Name** -- The name your customers know you by (if different) - **Support Email** -- Where your customers can reach you - **Website URL** -- Your business website - **Region and Timezone** -- Where you primarily operate - **Company Size** -- Helps us tailor the experience - **Logo Upload** -- Your brand identity across invoices, checkout, and emails ### Step 2: Business Profile Help us understand your business model so we can configure the right tools for you. - **Product Description** -- What you sell or the services you provide - **Customer Type** -- B2B, B2C, or both - **Customer Regions** -- Where your customers are located - **Billing Model** -- One-time, recurring subscriptions, usage-based, or a mix - **Billing Intervals** -- Monthly, quarterly, annual, or custom > **Note:** Not sure about your billing model yet? Choose what best describes your plans -- you can always adjust your product setup later. ### Step 3: Platform Usage Tell us how you plan to use RevKeen so we can recommend the right features and integrations. - **Primary Use Case** -- Your main reason for using RevKeen - **Customer-Facing Usage** -- Checkout links, hosted invoices, customer portal, etc. - **Technical Usage** -- API integrations, webhooks, embedded checkout, etc. - **Integration Notes** -- Any specific systems you need RevKeen to work with ### Step 4: Volume and Acquisition Share your expected transaction volumes. This helps us configure the right processing setup for your business. - **Expected Monthly Volume** -- Approximate monthly transaction count - **Average Transaction Value** -- Typical payment amount - **Current Payment Provider** -- If you are switching from another provider - **Go-Live Timeline** -- When you plan to start accepting payments ### Step 5: Contact and Preferences Set up your primary contact and communication preferences so our team can reach you during the review process. - **Contact Name and Email** -- Your primary point of contact - **Phone and Job Title** -- So we know who to ask for - **Sales Call** -- Optionally schedule a call with our team - **Email Preferences** -- Product updates, tips, and announcements ### Step 6: Review and Submit Review everything you have entered, confirm it is accurate, and submit your application. You will need to accept our Terms of Service and Privacy Policy. Once submitted, you will receive a confirmation email and an **application reference number** visible in your dashboard. Our team typically begins reviewing applications within one business day. > **Note:** Your 14-day trial and sandbox access are active from the moment you sign up -- you do not need to wait for the review to start exploring RevKeen. ## Identity Verification To protect your account and your customers, RevKeen requires identity verification before you can access certain sensitive actions like activating live payments or generating production API keys. Identity verification is handled as part of our application review process: - When you submit your onboarding application, our team reviews your business details - Once approved, your identity is verified and your account is unlocked for live payments - You will be notified when your account has been approved - No additional steps or documents are needed from you -- our team handles everything > **Note:** Identity verification is not required to explore RevKeen, set up products, or use the sandbox. It is only needed when you are ready to go live. ## What Happens After You Submit After completing the 6-step onboarding, here is what happens behind the scenes -- and what we handle for you. 1. **Application Review** -- Our team reviews your application details. You will receive an application reference in your dashboard to track status. We reply within one business day. 2. **Payment Gateway Provisioning** -- We configure your payment gateway, set up card processing, enable 3D Secure, and optionally activate Apple Pay and Google Pay -- all on your behalf. 3. **Testing and Quality Check** -- We run end-to-end tests on your payment setup -- card payments, refunds, 3D Secure flows, and wallet payments -- before handing over to you. 4. **Go Live** -- Once everything is verified and tested, we activate your live payment credentials. You will receive a confirmation and can start accepting real payments immediately. ## Getting Help If you have questions during onboarding or need assistance at any point, we are here to help: - **Support Portal** -- Submit a request directly from your RevKeen dashboard - **Email** -- Reach us at [info@revkeen.com](mailto:info@revkeen.com) - **Documentation** -- Browse our guides and API reference at [docs.revkeen.com](https://docs.revkeen.com) We typically respond to support requests within one business day. For onboarding-related questions, our team often replies within a few hours. > **Note:** During your trial period, you have full access to the sandbox environment for testing. Always test your checkout flow in sandbox mode before accepting real payments -- this helps catch configuration issues early. ## Next Steps - [Developer Quickstart](/docs/getting-started/quickstart) -- Go from staging key to first API call and first webhook delivery - [Products Guide](/docs/using-revkeen/products-and-pricing) -- Learn about products and pricing models - [Gateway Setup](/docs/getting-started/gateway-setup) -- Understand how payment gateway configuration works - [API Authentication](/docs/getting-started/authentication) -- Get your API keys for custom integrations --- # Authentication Source: https://docs.revkeen.com/docs/getting-started/authentication Authenticate with the RevKeen API using API keys or OAuth 2.1 RevKeen supports two authentication methods: **API keys** for server-to-server integrations and **OAuth 2.1** for MCP hosts, third-party apps, and automated workflows. ## API keys (recommended for most integrations) Use your RevKeen API key in the `x-api-key` header on every server-side REST request. ## Auth method ```http x-api-key: rk_live_your_api_key ``` If the header is missing, invalid, or belongs to the wrong environment, the API returns `401 Unauthorized`. ## Where to get keys Create API keys in the [RevKeen Dashboard](https://app.revkeen.com/developers/api-keys). Create separate keys for: - production services - staging and QA - each integration or backend service that needs isolated access ## Staging vs live | Key type | Prefix | Use when | |----------|--------|----------| | **Staging** | `rk_sandbox_*` | Integration development, QA, demos, and webhook testing | | **Live** | `rk_live_*` | Real customers, live transactions, and production automations | > **Note:** The non-production environment is documented as **Staging**, but the current key prefix remains `rk_sandbox_*`. ## Example ```bash curl https://staging-api.revkeen.com/v2/customers \ -H "x-api-key: rk_sandbox_your_api_key" \ -H "Accept: application/json" ``` ## Server-side key safety - Keep API keys in environment variables or a secret manager. - Never ship live keys to browsers, mobile apps, screenshots, or public repositories. - Rotate keys regularly and revoke keys that are no longer used. - Keep staging and production credentials fully separate. ## OAuth 2.1 For MCP integrations, third-party apps, and automated workflows, use OAuth 2.1 with `Authorization: Bearer rk_oauth_*` tokens. ```typescript const client = new RevKeenClient({ oauth: { clientId: process.env.REVKEEN_CLIENT_ID!, clientSecret: process.env.REVKEEN_CLIENT_SECRET!, scopes: ['customers:read', 'invoices:read'], }, }); ``` See the [OAuth 2.1 guide](/docs/getting-started/oauth) for authorization code + PKCE, client credentials, dynamic client registration, and scope reference. ## Next Steps - **OAuth 2.1** (/docs/getting-started/oauth): OAuth flows, scopes, and token lifecycle. - **Quickstart** (/docs/getting-started/quickstart): Go from staging key to first API call and first webhook delivery. - **Environments** (/docs/getting-started/environments): Production, staging, and mock guidance for safe rollout. - **API Reference** (/docs/api-reference): Interactive endpoint reference generated from the committed OpenAPI contract. --- # Core Concepts Source: https://docs.revkeen.com/docs/getting-started/core-concepts Understand the key building blocks of RevKeen RevKeen uses a relationship-based object model where entities connect to enable powerful billing workflows. Understanding these relationships is key to using the platform effectively. ## Object Hierarchy ``` +------------------------------------------------------------------+ | MERCHANT | | (Your Business Account) | +------------+---------------------------------------------+-------+ | | v v +----------------------+ +----------------------+ | PRODUCTS | | CUSTOMERS | | - Name, Description | | - Name, Email | | - Fulfillment Type | | - Payment Methods | | - Benefits | | - Addresses | +----------+-----------+ +-----------+----------+ | | v | +----------------------+ | | PRICES | | | - One-time | | | - Recurring | | | - Pay-what-you-want | | +----------+-----------+ | | | v | +----------------------+ | | CHECKOUT LINKS |<-------------------------------+ | - Public URL | | - Customization | | - Analytics | +----------+-----------+ | | v v +------------------------------------------------------------------+ | CHECKOUT SESSION | | (Customer completes payment) | +----------+-------------------------------------------+-----------+ | | v v +----------------------+ +----------------------+ | SUBSCRIPTIONS | | INVOICES | | (Recurring billing) | | - Invoice Line Items| | - Subscription Items+--------------------> - Due date | | - Trial period | | - Status lifecycle | +----------------------+ +-----------+----------+ | +----------------------+ | v +----------------------+ | ORDERS | | (Fulfillment) | | - Order Line Items | | - Tracking | +----------+-----------+ | v +----------------------+ | PAYMENTS | | - Payment attempts | | - Refunds | | - Disputes | +----------------------+ ``` ## Core Objects ### Product A product represents something you sell -- a physical item, digital download, or service. Products do not have prices directly; instead, you attach one or more **Prices** to a product. **Key Fields:** - `name` -- Display name - `description` -- Detailed description - `fulfillment_type` -- physical | digital | none (service) - `is_active` -- Whether product is available for sale ### Price A price defines how much a product costs and how it is billed. A single product can have multiple prices (e.g., monthly and annual billing options). **Price Types:** - **One-time** -- Single payment (e.g., $99) - **Recurring** -- Repeated billing (e.g., $29/month) - **Pay-what-you-want** -- Customer chooses amount ### Checkout Link (Payment Link) A checkout link is a shareable URL that customers can use to purchase your products. When a customer completes checkout, it creates an **Invoice**. For recurring products, a **Subscription** is also created. When paid invoices contain products with fulfillment, an **Order** is created. ### Customer A customer represents someone who has purchased from you or who you will invoice. Customers can have multiple payment methods and addresses. ### Invoice An invoice is a request for payment. Invoices can be **Manual** (created by you for custom charges) or **Automatic** (generated by subscriptions). **Invoice Line Item Sources:** - `price` -- From a product price - `order_line_item` -- From an order - `subscription_item` -- From a subscription - `adjustment` -- Manual adjustment ### Order An order is a fulfillment container created when a paid invoice contains products that require delivery (physical or digital). Orders are created for both one-time and recurring products that have a fulfillment type. ### Subscription A subscription represents ongoing recurring billing. Subscriptions automatically generate invoices at each billing period. > **Note:** **Subscription Items** allow multiple products in a single subscription, similar to Stripe's model. ### Event Events provide a complete audit trail of everything that happens in your account. Use events to track customer activity, payment history, and administrative actions. ## Learn More - [Core Objects Reference](/docs/using-revkeen/products-and-pricing) -- Detailed documentation for each object type - [Developer Quickstart](/docs/getting-started/quickstart) -- Go from staging key to first API call and first webhook delivery --- # Environments Source: https://docs.revkeen.com/docs/getting-started/environments Production, staging, and mock environments for the RevKeen API RevKeen exposes separate environments for live traffic, persisted pre-production testing, and schema-only mocking. ## Environment matrix | Environment | Base URL | Auth | Purpose | |-------------|----------|------|---------| | **Production** | `https://api.revkeen.com/v2` | `rk_live_*` via `x-api-key` | Live transactions and real customer data | | **Staging** | `https://staging-api.revkeen.com/v2` | `rk_sandbox_*` via `x-api-key` | Integration testing, QA, demos, and release validation | | **Mock** | `https://mock-api.revkeen.com/v2` | Auth not enforced | Schema validation, client prototyping, and CI smoke checks | ## Recommended promotion path 1. Start in **Mock** when you only need response shapes, frontend prototyping, or schema validation. 2. Move to **Staging** when you need persisted data, webhook delivery, and realistic lifecycle testing. 3. Promote to **Production** only after the same flows are stable in staging. ## Choosing the right environment | Scenario | Recommended environment | |----------|-------------------------| | UI prototyping or contract validation | **Mock** | | Local app integration and QA | **Staging** | | End-to-end billing flow validation | **Staging** | | Webhook testing | **Staging** | | Real customer traffic | **Production** | ## Environment-specific behavior - **Production** creates live side effects and should only be used with live keys and real workflows. - **Staging** is the default integration environment and the right place for webhook and end-to-end validation. - **Mock** does not persist state, does not emit webhooks, and does not validate tenant auth. > **Note:** Use **Mock** for shape validation. Use **Staging** when you need persistence, realistic lifecycle flows, or webhook testing. ## Next Steps - **Quickstart** (/docs/getting-started/quickstart): Use staging for the first successful request and webhook flow. - **API Reference** (/docs/api-reference): Interactive docs with production, staging, and mock switching. - **Authentication** (/docs/getting-started/authentication): Use `x-api-key` correctly and keep keys server-side. --- # First Payment Source: https://docs.revkeen.com/docs/getting-started/first-payment Create a product, generate a checkout link, and collect your first payment - How to create your first product in the RevKeen dashboard - How to set a price for your product - How to generate a checkout link and share it with customers - How to verify the payment appears in your dashboard ## Prerequisites Before you begin, make sure you have completed the following: - [Account Setup](/docs/getting-started/account-setup) -- Your RevKeen account is created and you can log in - [Gateway Setup](/docs/getting-started/gateway-setup) -- Your payment gateway is connected (test mode is fine) > **Note:** You can complete this entire guide using test mode. No real charges will be made. ## Step 1: Create a Product Products represent what you sell. Start by creating your first one. ### Navigate to Products In your RevKeen dashboard, go to **Products** in the sidebar navigation. ### Click "Create Product" Click the **Create Product** button in the top right corner. ### Fill in product details Enter the following information: - **Name** -- Give your product a clear name (e.g., "Starter Plan" or "Consulting Session") - **Description** -- A brief description of what the customer gets - **Fulfillment Type** -- Choose "None (Service)" for digital services, "Digital" for downloadable content, or "Physical" for shipped goods ### Save the product Click **Save** to create your product. You will be taken to the product detail page. ## Step 2: Set a Price Every product needs at least one price. For your first payment, we will create a simple one-time price. ### Add a price On the product detail page, click **Add Price** in the Prices section. ### Configure the price - **Price type** -- Select "One-time" for a single payment - **Amount** -- Enter the price (e.g., 29.00) - **Currency** -- Select your currency (e.g., USD) ### Save the price Click **Save** to attach the price to your product. ## Step 3: Generate a Checkout Link Checkout links are shareable URLs that take your customers directly to a hosted payment page. ### Create a checkout link From the product detail page, click **Create Checkout Link**, or navigate to **Checkout Links** in the sidebar and click **Create**. ### Select the product and price Choose the product and price you just created. Set the quantity to 1. ### Configure options Optionally customize: - **Success URL** -- Where to redirect after payment (e.g., your thank-you page) - **Branding** -- Your logo and colors will be applied automatically based on your account settings ### Generate the link Click **Create Link**. Your checkout link will be generated and displayed. ## Step 4: Share and Collect Payment Now you have a live checkout link ready to accept payments. ### Copy the link Copy the checkout URL from the dashboard. It will look something like: `https://checkout.revkeen.com/pay/lnk_xxxxxxxx` ### Test the checkout Open the link in a new browser tab. You will see the hosted checkout page with your product, price, and branding. ### Complete a test payment If you are in test mode, use one of the test card numbers: - **Visa (Approved):** `4111 1111 1111 1111` - **Mastercard (Approved):** `5431 1111 1111 1111` - Use any future expiration date and any CVV Fill in the card details and click **Pay**. > **Note:** You can share checkout links anywhere -- email, social media, your website, or embed them in a button. They work on any device. ## Step 5: View in Dashboard After the test payment completes, verify it in your dashboard. ### Check the Transactions page Navigate to **Transactions** in the sidebar. You should see your test payment listed with a "Completed" status. ### Check the Invoices page Navigate to **Invoices**. An invoice was automatically created for the payment, with the product and price as a line item. ### Check the Customers page Navigate to **Customers**. A customer record was created for the email address used during checkout. Congratulations -- you have processed your first payment with RevKeen! The dashboard shows the transaction, the invoice, and the customer, all linked together. ## What Happens Behind the Scenes When a customer completes checkout, RevKeen automatically: 1. **Creates a customer** record (or links to an existing one by email) 2. **Generates an invoice** with the product and price as line items 3. **Processes the payment** through your connected gateway 4. **Records the transaction** with full cost and margin tracking 5. **Sends a receipt** to the customer (if email notifications are enabled) ## Next Steps - [First Subscription](/docs/getting-started/first-subscription) -- Set up recurring billing - [Products and Pricing](/docs/using-revkeen/products-and-pricing) -- Explore advanced pricing models - [Checkout Customization](/docs/using-revkeen/checkout) -- Brand your checkout pages - [Webhooks](/docs/webhooks) -- Get notified when payments occur --- # First Subscription Source: https://docs.revkeen.com/docs/getting-started/first-subscription Set up your first recurring billing plan with trials and lifecycle management - How to create a product with recurring pricing - How to configure billing intervals (monthly, annual, etc.) - How to add an optional trial period - How to generate a checkout link for subscriptions - How to monitor the subscription lifecycle in the dashboard ## Prerequisites Before you begin, make sure you have completed the following: - [First Payment](/docs/getting-started/first-payment) -- You have successfully processed a one-time payment and are familiar with the product and checkout link workflow > **Note:** Everything in this guide works in test mode. No real charges will be made to any cards. ## Step 1: Create a Recurring Product Subscriptions in RevKeen start with a product that has a recurring price attached. ### Navigate to Products In your RevKeen dashboard, go to **Products** in the sidebar navigation and click **Create Product**. ### Fill in product details Enter information for your subscription product: - **Name** -- A clear name for the plan (e.g., "Pro Plan", "Growth Tier", "Monthly Membership") - **Description** -- What the subscriber gets (e.g., "Full access to all features, priority support, and unlimited usage") - **Fulfillment Type** -- Choose "None (Service)" for most SaaS subscriptions ### Save the product Click **Save** to create the product. ## Step 2: Set the Billing Interval Now add a recurring price to your product. This defines how much to charge and how often. ### Add a recurring price On the product detail page, click **Add Price** in the Prices section. ### Configure the recurring price - **Price type** -- Select "Recurring" - **Amount** -- Enter the price per interval (e.g., 29.00 for $29/month) - **Currency** -- Select your currency (e.g., USD) - **Interval** -- Choose the billing frequency: - **Monthly** -- Charged every month - **Quarterly** -- Charged every 3 months - **Annual** -- Charged every 12 months - **Custom** -- Set a custom interval count ### Save the price Click **Save** to attach the recurring price to your product. > **Note:** You can add multiple prices to the same product. For example, offer both a $29/month and a $290/year option so customers can choose their preferred billing cycle. ## Step 3: Add a Trial Period (Optional) Trial periods let customers try your product before being charged. The first invoice is generated at $0 during the trial, and billing begins automatically when the trial ends. ### Enable trial on the price When creating or editing a recurring price, look for the **Trial Period** section. ### Set the trial duration - **Trial days** -- Enter the number of free days (e.g., 7 or 14) - The customer's card is collected at checkout but not charged until the trial ends ### Save the updated price Click **Save** to apply the trial period. > **Note:** Trial periods require a valid payment method at checkout. The customer's card is authorized (not charged) to verify it is valid. Billing begins automatically when the trial period expires. ## Step 4: Create a Checkout Link Generate a shareable link so customers can subscribe. ### Create the checkout link Navigate to **Checkout Links** in the sidebar and click **Create**, or click **Create Checkout Link** from the product detail page. ### Select your recurring product Choose the subscription product and recurring price you created. Set quantity to 1. ### Configure checkout options Optionally customize: - **Success URL** -- Where to redirect after successful subscription (e.g., your welcome page or app dashboard) - **Allow promotion codes** -- Enable if you want customers to apply discount codes ### Generate and test the link Click **Create Link** to generate the checkout URL. Open it in a new tab and complete a test subscription using a test card: - **Visa (Approved):** `4111 1111 1111 1111` - Use any future expiration date and any CVV ## Step 5: Monitor the Subscription Lifecycle After a customer subscribes, RevKeen handles the entire lifecycle automatically. ### View active subscriptions Navigate to **Subscriptions** in the sidebar. Your new subscription will appear with an **Active** status (or **Trialing** if a trial period is configured). ### Review subscription details Click on the subscription to see: - **Status** -- Active, Trialing, Past Due, Canceled, etc. - **Current Period** -- The current billing period start and end dates - **Next Invoice Date** -- When the next automatic charge will occur - **Subscription Items** -- The products and prices included - **Payment Method** -- The card on file for automatic renewal ### Check automatic invoices Navigate to **Invoices**. You will see an invoice was automatically created when the subscription started. For subscriptions with trial periods, the first invoice will show a $0 amount. ### Track renewal events As the subscription renews, RevKeen automatically: - Generates a new invoice at each billing period - Charges the customer's card on file - Records the transaction with full margin tracking - Sends a receipt to the customer - Updates the subscription's current period ## Subscription Lifecycle Overview Understanding the subscription states helps you manage your billing effectively: | Status | Description | |---|---| | **Trialing** | Customer is in a free trial period. No charges yet. | | **Active** | Subscription is active and billing normally. | | **Past Due** | Payment failed. RevKeen will retry according to your dunning settings. | | **Canceled** | Subscription has been canceled. Access continues until the end of the current period. | | **Expired** | The subscription period has ended after cancellation. | | **Paused** | Subscription is temporarily paused. No invoices are generated. | > **Note:** When a payment fails, RevKeen automatically enters the **dunning** process -- retrying the charge and sending reminder emails to the customer. You can configure retry schedules and escalation rules in **Settings > Dunning**. ## What Happens Behind the Scenes When a customer completes a subscription checkout, RevKeen automatically: 1. **Creates or links a customer** record by email 2. **Creates a subscription** with the selected product, price, and billing interval 3. **Generates the first invoice** (at $0 for trials, or the full amount) 4. **Processes the initial payment** through your connected gateway 5. **Stores the payment method** securely for future renewals (Card on File) 6. **Schedules automatic renewals** at each billing interval 7. **Tracks margins** on every renewal, including processing costs ## Next Steps - [Subscriptions Guide](/docs/using-revkeen/subscriptions) -- Advanced subscription management, upgrades, downgrades, and cancellations - [Dunning](/docs/using-revkeen/dunning) -- Configure failed payment recovery - [Webhooks](/docs/webhooks) -- Get notified of subscription events (`subscription.created`, `subscription.renewed`, `subscription.canceled`) - [Customer Portal](/docs/using-revkeen/customer-portal) -- Let customers manage their own subscriptions --- # Gateway Setup Source: https://docs.revkeen.com/docs/getting-started/gateway-setup Connect your payment processor to RevKeen - How to connect your NMI payment gateway to RevKeen - How to configure test and production environments - How tokenization keeps card data secure - How to verify your gateway connection RevKeen integrates with NMI (Network Merchants Inc.) as the primary payment gateway. This guide walks you through connecting your gateway and configuring it for both test and production environments. ## Supported Payment Gateways - **NMI Gateway** -- Full support including tokenization, recurring billing, 3DS verification, and ACH payments. - **Elavon** -- RevKeen's payment processing partner. One of the world's largest processors with direct acquiring, multi-currency, and card-present support via PAX terminals. ## Prerequisites - An NMI merchant account ([nmi.com](https://www.nmi.com)) - Access to your NMI merchant portal - API Security Key from NMI settings - Collect.js tokenization key (for secure card collection) ## NMI Gateway Setup ### Get Your API Security Key 1. Log in to your NMI merchant portal 2. Navigate to **Settings > Security Keys** 3. Generate a new API Security Key or copy an existing one 4. Keep this key secure -- it provides full API access > **Note:** Never expose your API Security Key in client-side code. It should only be stored securely on your server or in RevKeen's encrypted settings. ### Get Your Collect.js Tokenization Key 1. In the NMI portal, go to **Settings > Collect.js** 2. Create a new tokenization key 3. Set the allowed domains (your checkout URLs) 4. Copy the generated tokenization key > **Note:** The tokenization key is safe to use in client-side code. It only allows card tokenization, not actual charges. ### Configure Gateway in RevKeen 1. Go to **Settings > Payment Gateway** in your RevKeen dashboard 2. Select **NMI** as your gateway provider 3. Enter your API Security Key 4. Enter your Collect.js Tokenization Key 5. Click **Save and Verify** ### Test Your Connection RevKeen will verify your credentials by performing a zero-dollar authorization. If successful, your gateway status will show as **Connected**. Run a test payment using one of the test cards below to verify the full flow. ## Test Card Numbers Use these test cards in sandbox/test mode to simulate various scenarios: | Card Number | Brand | Result | |---|---|---| | `4111111111111111` | Visa | Approved | | `5431111111111111` | Mastercard | Approved | | `341111111111111` | Amex | Approved | | `4000000000000002` | Visa | Declined | | `4000000000003220` | Visa | 3DS Required | > **Note:** Use any future expiration date (e.g., 12/28) and any 3-digit CVV (or 4-digit for Amex) when testing. ## Test vs Production Mode | Mode | Use Case | Real Charges | |---|---|---| | Test | Development, QA, demos | No | | Production | Live customer payments | Yes | Toggle between modes in **Settings > Payment Gateway > Environment**. > **Note:** Always thoroughly test in Test mode before switching to Production. Production transactions will charge real cards and cannot be easily undone. ## How Payment Flow Works 1. **Customer Enters Card** -- Card details entered in RevKeen's secure checkout form. 2. **Collect.js Tokenization** -- Card tokenized client-side -- raw card data never touches your servers. 3. **RevKeen Processes Payment** -- Token sent to RevKeen API, which calls NMI to process the charge. 4. **Result Returned** -- Success or decline response, customer redirected appropriately. ## API Configuration (Optional) If you are using the RevKeen API to process payments programmatically, ensure your gateway is configured before making charge requests. ```typescript // Gateway configuration is managed in the dashboard // API calls automatically use your configured gateway const payment = await client.payments.create({ customerId: 'cus_xxxxxxxx', amount: 9900, // $99.00 in cents currency: 'USD', paymentMethodToken: 'tok_xxxxxxxx', // From Collect.js description: 'Pro Plan Subscription', }); if (payment.data.status === 'succeeded') { console.log('Payment successful:', payment.data.transactionId); } ``` ```python # Gateway configuration is managed in the dashboard # API calls automatically use your configured gateway payment = client.payments.create( customer_id="cus_xxxxxxxx", amount=9900, # $99.00 in cents currency="USD", payment_method_token="tok_xxxxxxxx", # From Collect.js description="Pro Plan Subscription" ) if payment.data.status == "succeeded": print(f"Payment successful: {payment.data.transaction_id}") ``` ## Troubleshooting ### "Invalid API Key" error Verify you copied the complete API Security Key from NMI. Check there are no extra spaces or missing characters. ### Collect.js not loading Ensure your domain is added to the allowed domains in NMI's Collect.js settings. Include both your development and production URLs. ### Test payments work but production fails Check that your NMI account is fully activated for live processing. Some accounts require additional verification before going live. ## Next Steps - [Checkout Integration](/docs/using-revkeen/checkout) -- Integrate hosted checkout pages - [Developer Quickstart](/docs/getting-started/quickstart) -- Complete the first API call and webhook flow - [Payments Guide](/docs/using-revkeen/payments-and-refunds) -- Learn about payment processing - [Webhooks](/docs/webhooks) -- Set up payment event notifications --- # OAuth 2.1 Source: https://docs.revkeen.com/docs/getting-started/oauth Use OAuth 2.1 for MCP integrations, third-party apps, and server-to-server automation RevKeen supports OAuth 2.1 alongside API keys. Use OAuth when building MCP integrations, third-party apps, or automated workflows that act on behalf of a merchant. ## When to use OAuth vs API keys | Use case | Recommended auth | |----------|------------------| | Server-to-server from your own backend | API key (`x-api-key`) | | MCP host (Claude Desktop, Cursor, VS Code) | OAuth (authorization code + PKCE or client credentials) | | Third-party app acting on behalf of a merchant | OAuth (authorization code + PKCE) | | Automated workflow or CI/CD pipeline | OAuth (client credentials) | | Quick prototyping or cURL testing | API key | ## Supported flows ### Authorization Code + PKCE Best for user-facing integrations where a merchant grants access interactively. 1. Redirect the merchant to the authorization endpoint 2. Merchant approves the requested scopes 3. Exchange the authorization code for tokens ``` GET https://app.revkeen.com/api/auth/oauth2/authorize ?client_id=YOUR_CLIENT_ID &redirect_uri=https://yourapp.com/callback &response_type=code &code_challenge=CHALLENGE &code_challenge_method=S256 &scope=customers:read invoices:read ``` ### Client Credentials Best for server-to-server workflows where no user interaction is needed. ```bash curl -X POST https://api.revkeen.com/api/auth/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=YOUR_CLIENT_ID" \ -d "client_secret=YOUR_CLIENT_SECRET" \ -d "scope=customers:read invoices:read" ``` ### Dynamic Client Registration MCP hosts that support RFC 7591 can auto-register as OAuth clients: ``` POST https://api.revkeen.com/api/auth/oauth2/register ``` ## Token lifecycle | Token | Lifetime | Notes | |-------|----------|-------| | Access token | 1 hour | Prefix: `rk_oauth_*` | | Refresh token | 7 days | Use to obtain new access tokens | Access tokens are sent via the `Authorization` header: ```http Authorization: Bearer rk_oauth_xxxxxxxx ``` ## SDK examples ### TypeScript ```typescript const client = new RevKeenClient({ oauth: { clientId: process.env.REVKEEN_CLIENT_ID!, clientSecret: process.env.REVKEEN_CLIENT_SECRET!, scopes: ['customers:read', 'invoices:read'], }, }); const customers = await client.customers.list(); ``` The SDK handles token acquisition, caching, and refresh automatically via `OAuthTokenManager`. ### Go ```go client := revkeen.NewClient( option.WithOAuth(revkeen.OAuthConfig{ ClientID: os.Getenv("REVKEEN_CLIENT_ID"), ClientSecret: os.Getenv("REVKEEN_CLIENT_SECRET"), Scopes: []string{"customers:read", "invoices:read"}, }), ) ``` ### cURL ```bash # 1. Get access token TOKEN=$(curl -s -X POST https://api.revkeen.com/api/auth/oauth2/token \ -d "grant_type=client_credentials" \ -d "client_id=$REVKEEN_CLIENT_ID" \ -d "client_secret=$REVKEEN_CLIENT_SECRET" \ -d "scope=customers:read" | jq -r '.access_token') # 2. Use it curl https://api.revkeen.com/v2/customers \ -H "Authorization: Bearer $TOKEN" ``` ## Scopes Scopes follow `{resource}:{action}` format. Request only the scopes your integration needs. | Pattern | Meaning | |---------|---------| | `customers:read` | Read customer data | | `invoices:write` | Create and manage invoices | | `subscriptions:*` | Full subscription access | | `*` | All scopes (avoid in production) | See the full scope table in the [API Reference](/docs/api-reference). ## Well-known endpoints | Endpoint | URL | |----------|-----| | OAuth Authorization Server Metadata (RFC 8414) | `https://api.revkeen.com/.well-known/oauth-authorization-server` | | OpenID Connect Discovery | `https://api.revkeen.com/.well-known/openid-configuration` | | MCP OAuth Metadata | `https://api.revkeen.com/.well-known/oauth-authorization-server/mcp` | ## Next Steps - **Authentication** (/docs/getting-started/authentication): API key authentication reference. - **MCP** (/docs/mcp): Connect RevKeen tools to AI hosts over MCP. - **API Reference** (/docs/api-reference): Interactive endpoint reference generated from the committed OpenAPI contract. --- # Quickstart Source: https://docs.revkeen.com/docs/getting-started/quickstart Go from staging key to first API call and first webhook delivery This is the fastest path from zero to first success with the RevKeen REST API. > **Note:** Use **Staging** first. Staging uses `rk_sandbox_*` keys and the base URL `https://staging-api.revkeen.com/v2`. ## 1. Create a staging key Create a non-production key in the [RevKeen Dashboard](https://app.revkeen.com/developers/api-keys). - Create a new key for staging or integration work. - Store it in an environment variable on your server. - Do not expose it in browser code or mobile apps. ```bash export REVKEEN_API_KEY=rk_sandbox_your_api_key ``` ## 2. Make your first API call Start with a safe read request against staging: ```bash curl https://staging-api.revkeen.com/v2/customers \ -H "x-api-key: $REVKEEN_API_KEY" \ -H "Accept: application/json" ``` If the key and environment match, you will get a `200 OK` response with a list payload. ## 3. Register one webhook endpoint Create a staging webhook endpoint that subscribes to `customer.created`. ```bash curl https://staging-api.revkeen.com/v2/webhook-endpoints \ -X POST \ -H "x-api-key: $REVKEEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com/webhooks/revkeen", "enabled_events": ["customer.created"], "description": "Staging webhook endpoint" }' ``` Store the returned signing secret securely. You will need it to verify the `X-RevKeen-Signature` header on incoming deliveries. ## 4. Trigger one event Create a customer in staging to trigger the webhook you just subscribed to: ```bash curl https://staging-api.revkeen.com/v2/customers \ -X POST \ -H "x-api-key: $REVKEEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "email": "quickstart@example.com", "name": "Quickstart Customer" }' ``` Confirm that your endpoint receives a `customer.created` event and that your consumer: - verifies the signature - logs the event ID - returns `2xx` quickly ## 5. Choose the next surface - **Full API Reference** (/docs/api-reference): Use the API reference for endpoint-level details, schemas, examples, auth, and request testing. - **SDKs** (/docs/sdks): Move to the official TypeScript, Python, or PHP SDK once the first curl flow is working. - **Webhooks** (/docs/webhooks): Tighten verification, retry handling, and operational guidance for production. --- # Using RevKeen Source: https://docs.revkeen.com/docs/using-revkeen Core workflows for managing customers, products, subscriptions, and payments These guides walk you through common workflows and best practices for using RevKeen's billing platform. Whether you are integrating via the API or managing everything from the dashboard, the sections below cover every core concept. ## Core Concepts - **[Customers](/docs/using-revkeen/customers)** -- Create and manage customer profiles with billing information and payment methods. - **[Products and Pricing](/docs/using-revkeen/products-and-pricing)** -- Define your product catalog with flexible pricing models and discount codes. ## Checkout and Payments - **[Checkout](/docs/using-revkeen/checkout)** -- Use hosted checkout for secure, PCI-compliant payment collection. - **[Subscriptions](/docs/using-revkeen/subscriptions)** -- Manage recurring billing with trials, discounts, and plan changes. - **[Invoices and Orders](/docs/using-revkeen/invoices-and-orders)** -- Generate and send professional invoices with automatic payment collection. ## Operations and Recovery - **[Payments and Refunds](/docs/using-revkeen/payments-and-refunds)** -- Process payments, handle declines, and issue refunds. - **[Dunning](/docs/using-revkeen/dunning)** -- Automatic payment retry and recovery for failed subscription payments. - **[Disputes](/docs/using-revkeen/disputes)** -- Handle chargebacks and payment disputes effectively. - **[Benefits](/docs/using-revkeen/benefits)** -- Attach digital benefits and entitlements to products and subscriptions. - **[Customer Portal](/docs/using-revkeen/customer-portal)** -- Give customers self-service access to manage their accounts. ## Object Relationships Understanding how RevKeen objects relate to each other is essential for building effective billing workflows. - **Products to Prices** -- A product can have multiple prices (e.g., monthly at $29 and annual at $290). - **Prices to Checkout Links** -- A checkout link references one or more prices to create a purchasable offering. - **Checkout to Invoices to Orders/Subscriptions** -- Completing checkout creates an Invoice. For recurring products, a Subscription is created. For products with fulfillment, an Order is created when the invoice is paid. - **Subscriptions to Invoices to Orders** -- Subscriptions generate invoices at each billing period. Paid invoices with fulfillable items create orders. - **Invoices to Payments** -- Invoices track payment attempts, success, refunds, and disputes. - **Everything to Events** -- All actions generate events for a complete audit trail. ## Quick Reference ### Object Summary | Object | Purpose | Key Relationship | |--------|---------|------------------| | Product | Define what you sell | Has many Prices | | Price | Define how much and how often | Belongs to Product | | Checkout Link | Shareable purchase URL | References Prices | | Customer | Who you bill | Has many Orders, Subscriptions | | Order | Fulfillment tracking | Created from paid Invoice | | Subscription | Recurring billing | Generates Invoices periodically | | Invoice | Payment request | Has many Line Items | | Discount | Promotional pricing | Applied to Orders/Subscriptions | | Event | Audit trail | References all objects | ### Billing Intervals | Interval | Description | Example | |----------|-------------|---------| | `day` | Daily billing | Every day, every 3 days | | `week` | Weekly billing | Every week, every 2 weeks | | `month` | Monthly billing | Every month, quarterly | | `year` | Yearly billing | Every year, every 2 years | ### Supported Currencies | Code | Currency | Minor Unit | |------|----------|------------| | `USD` | US Dollar | Cents (100) | | `EUR` | Euro | Cents (100) | | `GBP` | British Pound | Pence (100) | | `CAD` | Canadian Dollar | Cents (100) | | `AUD` | Australian Dollar | Cents (100) | ### User Roles | Role | Description | Permissions | |------|-------------|-------------| | `owner` | Account owner | Full access, billing, team management | | `admin` | Administrator | Full access except billing | | `member` | Team member | Read/write customers, products, invoices | | `viewer` | Read-only | View-only access to all data | --- # Benefits Source: https://docs.revkeen.com/docs/using-revkeen/benefits Attach digital benefits and entitlements to products and subscriptions Benefits define what customers receive when they purchase a product. Configure automatic file delivery, license keys, custom webhooks, or manual fulfillment for your products. ## What are Benefits? Benefits are the deliverables attached to your products: - **Digital files** -- PDFs, videos, software downloads - **License keys** -- Software activation codes - **Access grants** -- Membership or course access - **Webhook triggers** -- External system notifications - **Custom actions** -- Any automated fulfillment ## Benefit Types | Type | Description | Delivery | |------|-------------|----------| | **File Download** | Digital files for customer download | Automatic after payment | | **License Key** | Software license or activation code | Email + Customer Portal | | **Custom** | External webhook or integration | Via webhook/API | | **Manual** | Requires manual fulfillment | You fulfill manually | ## Creating a Benefit 1. Go to **Products > Benefits** 2. Click **New Benefit** 3. Select the benefit type 4. Configure the benefit settings 5. Attach to products ## File Download Benefits For digital products like ebooks, courses, or software: 1. Select **File Download** as benefit type 2. Upload your file(s) 3. Set download limits (optional): - Maximum downloads per purchase - Download expiration period 4. Configure access: - Unique download links per customer - Available in Customer Portal > Files are served via secure, expiring URLs. Customers cannot share direct download links. ## License Key Benefits For software products requiring activation: ### Key Generation Options - **Auto-generate** -- RevKeen creates unique keys - **Pre-upload** -- Import a list of keys to distribute - **External API** -- Call your API to generate keys ### Key Settings - **Format** -- Define key pattern (e.g., XXXX-XXXX-XXXX) - **Activation limit** -- Number of allowed activations - **Expiration** -- Key validity period ## Custom (Webhook) Benefits For integration with external systems: 1. Select **Custom** benefit type 2. Enter your webhook URL 3. Configure the payload: - Customer information - Order/subscription details - Custom metadata 4. Test the webhook Common use cases: - Grant access in your application - Create accounts in external systems - Trigger provisioning workflows - Update CRM/marketing tools ## Attaching Benefits to Products A product can have multiple benefits: 1. Open the product in the catalogue 2. Go to the **Benefits** tab 3. Click **Add Benefit** 4. Select existing benefit or create new 5. Configure when benefit is delivered: - Immediately after payment - After subscription activation - On specific events ## Benefits for Subscriptions Configure how benefits work with recurring products: | Behavior | Description | |----------|-------------| | **Grant on activation** | Benefit delivered when subscription starts | | **Grant on each renewal** | New benefit delivered each billing cycle | | **Revoke on cancellation** | Access removed when subscription ends | | **Keep on cancellation** | Access remains after subscription ends | ## Tracking Fulfillment View benefit delivery status in Orders: - **Pending** -- Awaiting delivery - **Delivered** -- Successfully fulfilled - **Failed** -- Delivery error (retry available) - **Revoked** -- Access removed ## Related - [Products and Pricing](/docs/using-revkeen/products-and-pricing) -- Understanding product objects - [Invoices and Orders](/docs/using-revkeen/invoices-and-orders) -- Order fulfillment tracking - [Customer Portal](/docs/using-revkeen/customer-portal) -- Customer access to benefits --- # Checkout Source: https://docs.revkeen.com/docs/using-revkeen/checkout Create checkout links, customize the payment experience, and track conversions Checkout Sessions provide a hosted payment page that handles payment collection, card validation, and 3D Secure authentication. They are the fastest way to start accepting payments. This page covers checkout sessions, hosted checkout, checkout links, and customization. ## How It Works 1. **Create a Checkout Session** -- Your server creates a session with line items and redirect URLs. 2. **Redirect to Checkout** -- Redirect the customer to the hosted checkout page. 3. **Customer Pays** -- Customer enters payment details on the secure page. 4. **Confirmation** -- Customer is redirected to your success URL with session details. 5. **Webhook (Optional)** -- Receive a `checkout.session.completed` webhook. ## Creating a Checkout Session ```typescript const session = await client.checkout.sessions.create({ // Associate with an existing customer (optional) customerId: 'cus_xxxxxxxx', // Line items to purchase lineItems: [ { productId: 'prod_xxxxxxxx', quantity: 1, }, ], // Where to redirect after checkout successUrl: 'https://yourapp.com/success?session_id={CHECKOUT_SESSION_ID}', cancelUrl: 'https://yourapp.com/cancel', // Optional: Allow promo codes allowPromotionCodes: true, // Optional: Collect billing address billingAddressCollection: 'required', }); // Redirect customer to checkout return redirect(session.data.url); ``` ```python session = client.checkout.sessions.create( customer_id="cus_xxxxxxxx", line_items=[ {"product_id": "prod_xxxxxxxx", "quantity": 1} ], success_url="https://yourapp.com/success?session_id={CHECKOUT_SESSION_ID}", cancel_url="https://yourapp.com/cancel", allow_promotion_codes=True, billing_address_collection="required" ) return redirect(session.data.url) ``` > The `{CHECKOUT_SESSION_ID}` placeholder in your success URL will be replaced with the actual session ID. ## Session Modes | Mode | Description | Use Case | |------|-------------|----------| | `payment` | One-time payment | Single purchases, one-time fees | | `subscription` | Recurring payment | Subscriptions, memberships | | `setup` | Save payment method only | Collect card for future use | ## Subscription Checkout For recurring products, the session automatically creates a subscription: ```typescript const session = await client.checkout.sessions.create({ mode: 'subscription', customerId: 'cus_xxxxxxxx', lineItems: [ { productId: 'prod_monthly_plan', quantity: 1, }, ], subscriptionData: { trialDays: 14, }, successUrl: 'https://yourapp.com/welcome', cancelUrl: 'https://yourapp.com/pricing', }); ``` ## Handling Success When a customer completes checkout, they are redirected to your success URL. Retrieve the session to verify payment: ```typescript // In your success page handler const sessionId = searchParams.get('session_id'); const session = await client.checkout.sessions.retrieve(sessionId); if (session.data.paymentStatus === 'paid') { // Payment successful - fulfill the order const customerId = session.data.customerId; const subscriptionId = session.data.subscriptionId; await fulfillOrder(session.data); } ``` > **Important:** Don't rely solely on the success redirect. Use webhooks to handle payment confirmation for critical fulfillment logic. --- ## Hosted Checkout RevKeen Hosted Checkout provides secure, professionally designed payment pages that handle all the complexity of collecting payments while maximizing conversion rates. ### What is Hosted Checkout? Hosted Checkout is a complete payment page hosted by RevKeen: - **Fully managed** -- No code required - **PCI compliant** -- Handles sensitive card data securely - **Mobile optimized** -- Works on any device - **Conversion optimized** -- Designed for maximum conversions - **Customizable** -- Match your brand ### Checkout Page Elements | Element | Description | |---------|-------------| | **Product info** | Name, description, image, price | | **Email field** | Customer email (required) | | **Billing address** | Address for the invoice (configurable) | | **Payment form** | Card details or other payment methods | | **Discount code** | Optional promo code field | | **Custom fields** | Any additional fields you configure | | **Terms checkbox** | Accept terms and conditions | ### Supported Payment Methods | Method | Description | |--------|-------------| | **Credit/Debit Cards** | Visa, Mastercard, American Express, Discover | | **ACH Bank Transfer** | Direct bank payments (US) | | **Apple Pay** | One-tap payments on Apple devices (Safari on macOS/iOS) | | **Google Pay** | One-tap payments on devices with Google Pay configured | > Available payment methods depend on your gateway configuration. Apple Pay and Google Pay must be enabled in **Settings > Checkout Appearance**. ### Apple Pay and Google Pay RevKeen supports Apple Pay and Google Pay as additional payment methods on your hosted checkout pages. When enabled, customers see wallet tabs alongside the standard card payment form. #### Enabling Wallet Payments 1. Go to **Settings > Checkout Appearance** 2. Scroll to **Wallet Payment Methods** 3. Toggle **Apple Pay** and/or **Google Pay** on 4. Click **Save** #### Device Compatibility | Method | Supported Devices | |--------|-------------------| | **Apple Pay** | Safari on macOS, iOS, and iPadOS with Apple Pay configured | | **Google Pay** | Chrome, Safari, Firefox, and Edge on devices with Google Pay | The wallet tabs automatically appear only on supported devices. Customers on unsupported devices will see the standard card payment form. #### Limitations - **Auto-charge subscriptions** -- Apple Pay cannot be used for subscriptions with automatic renewal billing. Customers will be prompted to use a card instead. - **Card vaulting** -- Wallet tokens are one-time use and cannot be saved for future payments. ### Returning Customers and Saved Cards When a returning customer enters their email, the checkout detects whether they have saved cards on file and presents two checkout paths: #### Express Checkout (Saved Card) Customers can pay quickly using a previously saved card. For security, saved cards are only shown after the customer verifies their identity: 1. Customer enters their email address 2. Checkout detects saved cards and shows **Express checkout** and **Pay manually** options 3. Customer selects **Express checkout** 4. If the customer has a **trusted device** (returning browser), their saved cards appear immediately 5. Otherwise, a **6-digit verification code** is sent to their email 6. After verification, saved cards are displayed 7. Customer selects a card, enters the **CVV**, and completes payment > After a successful email verification, the browser is remembered as a trusted device for 30 days. The customer won't need to verify again on future visits from the same browser. #### Manual Payment (New Card) Always available alongside express checkout. Customers can enter new card details without any verification. This ensures nobody is blocked if email delivery is slow or they prefer to use a different card. #### Saved Card Security Saved card access is protected by multiple security layers: | Protection | Detail | |-----------|--------| | **Email verification** | 6-digit OTP sent to the customer's email before showing saved cards | | **Trusted device** | Verified browsers are remembered for 30 days (skips OTP on return visits) | | **CVV re-entry** | Customer must re-enter their card's CVV for every saved card payment | | **Rate limiting** | Max 3 verification attempts per code, 3 codes per 15 minutes | | **Credential on File** | All saved card charges comply with card network CoF rules | ### Success and Cancel URLs Configure where customers go after checkout: | URL Type | When Used | |----------|-----------| | **Success URL** | After successful payment | | **Cancel URL** | If customer abandons checkout | URL parameters available on success redirect: - `checkout_id` -- Checkout session ID - `customer_id` -- Customer ID - `order_id` -- Order ID (for one-time) - `subscription_id` -- Subscription ID (for recurring) ### Pre-filling Customer Data Pre-fill checkout fields using URL parameters: ``` https://checkout.revkeen.com/pay/xyz123 ?email=john@example.com &name=John%20Doe &discount=SUMMER20 ``` ### Security Hosted checkout provides enterprise-grade security: - **PCI DSS Level 1** -- Highest level of compliance - **HTTPS everywhere** -- All traffic encrypted - **3D Secure** -- Additional authentication when required - **Fraud detection** -- Built-in fraud prevention - **Session timeouts** -- Automatic expiration - **Saved card verification** -- Email OTP + CVV required before using saved cards - **Trusted device cookies** -- Secure, HttpOnly cookies scoped per merchant and customer --- ## Checkout Links Checkout Links (also called Payment Links) are shareable URLs that let you accept payments without writing any code. Share them via email, social media, QR codes, or embed them on your website. ### What is a Checkout Link? A Checkout Link is a pre-configured URL that opens a hosted checkout page. When a customer clicks the link, they see your product details, enter their payment information, and complete the purchase. Example checkout link: `https://checkout.revkeen.com/l/pl_abc123xyz` ### Use Cases - **Email campaigns** -- Include payment links in marketing emails for direct conversion - **Social media** -- Share links on Twitter, LinkedIn, or Instagram bio - **QR codes** -- Generate QR codes for in-person events or printed materials - **Invoices** -- Include payment links in custom invoices or proposals ### Creating Checkout Links #### Via Dashboard 1. Navigate to **Product > Checkout Links** 2. Click **+ New Link** 3. Select one or more products/prices to include 4. Configure options (quantity, discounts, custom fields) 5. Customize the checkout appearance (optional) 6. Save and copy the link URL #### Via API ```typescript const link = await client.paymentLinks.create({ priceId: 'price_xxxxxxxx', // Optional settings allowQuantity: true, allowDiscountCodes: true, collectBillingAddress: true, successUrl: 'https://yoursite.com/thank-you', cancelUrl: 'https://yoursite.com/checkout-cancelled', metadata: { campaign: 'summer-sale', source: 'email' } }); console.log(link.data.url); // https://checkout.revkeen.com/l/pl_xxx ``` ### Configuration Options | Option | Description | Default | |--------|-------------|---------| | `allow_quantity` | Let customers choose quantity | false | | `allow_discount_codes` | Show discount code input field | false | | `collect_billing_address` | Require full billing address | false | | `is_business_purchase` | Collect business information | false | | `success_url` | Redirect after successful payment | RevKeen success page | | `cancel_url` | Redirect if customer cancels | None | ### What Happens After Checkout When a customer completes checkout through a link: 1. **Customer record created** (if new) or matched (if existing) 2. **Order or Subscription created** depending on price type 3. **Invoice generated** for the purchase 4. **Payment processed** via your payment gateway 5. **Confirmation email sent** to customer 6. **Webhooks fired** for your integrations 7. **Customer redirected** to success page ### Tracking and Analytics RevKeen tracks performance metrics for each checkout link: | Metric | Description | |--------|-------------| | Views | Number of times the checkout page was loaded | | Sessions Started | Number of checkout sessions initiated | | Completions | Number of successful purchases | | Conversion Rate | Completions / Views percentage | | Revenue | Total revenue from the link | | Abandonment Rate | Sessions started but not completed | --- ## Checkout Customization Customize your checkout pages to match your brand and optimize for conversions. ### Branding Options | Option | Description | |--------|-------------| | **Logo** | Your logo displayed at the top | | **Primary Color** | Button and accent color | | **Background Color** | Page background | | **Button Text** | Customize the pay button text | | **Favicon** | Browser tab icon | ### Accessing Customization 1. Go to **Settings > General** 2. Scroll to **Checkout Appearance** 3. Configure your branding options 4. Preview changes in real-time 5. Save your settings ### Form Field Configuration Control which fields appear on checkout: | Field | Options | |-------|---------| | **Email** | Always required | | **Name** | Required, optional, or hidden | | **Phone** | Required, optional, or hidden | | **Billing Address** | Full address, country only, or hidden | | **Shipping Address** | Required, optional, or hidden | > Fewer fields typically increase conversion rates. Only collect information you actually need. ### Custom Fields Add your own fields to collect additional information: 1. Go to **Settings > Custom Fields** 2. Create a field with entity type "Checkout" 3. Choose the field type (text, select, etc.) 4. Mark as required if needed 5. The field appears on all checkouts (or specific ones) Examples of custom checkout fields: - T-shirt size for merchandise - Company name for B2B sales - Purchase order number - How did you hear about us? - License plate (parking services) ### Discount Code Field Configure the promo code field: - **Show always** -- Field visible by default - **Show on click** -- "Have a promo code?" link - **Hide** -- No discount field shown - **Pre-apply** -- Auto-apply a specific discount ### Terms and Conditions Add required agreement checkboxes: 1. Go to **Checkout Appearance** 2. Enable **Terms Checkbox** 3. Enter checkbox text and link to your terms 4. Optionally add a privacy policy link Example checkbox text: ``` I agree to the [Terms of Service](https://yoursite.com/terms) and [Privacy Policy](https://yoursite.com/privacy) ``` ### Product Display Options Configure how products appear on checkout: - **Product image** -- Show/hide product image - **Description** -- Show/hide product description - **Quantity selector** -- Allow customers to adjust quantity - **Price breakdown** -- Show subtotal, taxes, discounts ### Subscription-Specific Options For recurring products: - **Billing frequency** -- Show monthly/yearly toggle - **Trial messaging** -- Customize trial period text - **Future billing** -- Show when next charge occurs - **Cancellation policy** -- Display cancellation terms ### Confirmation Page Customize the post-purchase experience: - **Success message** -- Thank you text - **Next steps** -- What happens next - **Call to action** -- Button to your site or portal - **Custom redirect** -- Redirect to your own page ### Mobile Optimization Checkout is automatically optimized for mobile: - Responsive layout for all screen sizes - Touch-friendly input fields - Mobile payment methods (Apple Pay, Google Pay) - Numeric keyboard for card numbers - Auto-zoom prevention ### Checkout Link Best Practices 1. **Create dedicated links for campaigns** -- Use separate links for different marketing channels to track performance. 2. **Use metadata for attribution** -- Add campaign, source, or medium to link metadata for detailed analytics. 3. **Set custom success URLs** -- Redirect to your own thank-you page for upsells or next steps. 4. **Enable discount codes for promotions** -- Allow customers to apply discounts during checkout for special offers. ## Related - [Subscriptions](/docs/using-revkeen/subscriptions) -- Learn about subscription lifecycle management - [Payments and Refunds](/docs/using-revkeen/payments-and-refunds) -- Handle payment processing - [Customer Portal](/docs/using-revkeen/customer-portal) -- Post-purchase experience --- # Customer Health Scores Source: https://docs.revkeen.com/docs/using-revkeen/customer-health-scores Understand customer health scores, AI-powered intelligence, payment failure predictions, and churn risk analysis ## Customer Health Score RevKeen automatically calculates a **health score** (0--100) for each customer based on their payment behaviour. The score helps you identify at-risk customers before they churn and prioritise outreach to accounts that need attention. ### How the Score Works The health score is a weighted composite of five components: | Component | Weight | What it Measures | |-----------|--------|-----------------| | Punctuality | 30% | Ratio of invoices paid on time and average days to pay | | Dunning | 25% | How deep a customer goes into dunning and whether they self-recover | | Payment Failures | 20% | Failed transaction rate over the last 6 months, with extra penalty for hard declines and fraud flags | | Tenure | 15% | How long the customer has been active, plus score trend over time | | Method Health | 10% | Whether the customer's default payment method is valid and not expiring soon | ### Risk Levels Each customer is assigned a risk level based on their overall score: | Score Range | Risk Level | Meaning | |-------------|-----------|---------| | 80--100 | Excellent | Reliable payer, no action needed | | 60--79 | Good | Generally healthy, minor issues possible | | 40--59 | Needs Monitoring | Some payment problems -- consider proactive outreach | | 0--39 | High Risk | Significant payment issues -- immediate attention recommended | ### Where to View Health Scores - **Dashboard home** -- The Customer Health summary card shows the average score across all customers and a breakdown by risk level - **Customer list** -- Each customer displays a colour-coded health score pill next to their name - **Customer detail** -- The Health Score widget shows the overall score, risk level, trend direction, and a breakdown of all five component scores with a **Recalculate** button for on-demand updates ### Recalculation Schedule Health scores are automatically recalculated **daily at 03:00 UTC** for all customers with invoice history. You can also trigger an immediate recalculation for any individual customer from their detail page. ### Trend Tracking RevKeen tracks score changes over time and labels each customer with a trend: - **Improving** -- Score increased by 5+ points since last calculation - **Stable** -- Score within 5 points of last calculation - **Declining** -- Score dropped by 5+ points since last calculation Use the trend indicator to catch customers whose payment behaviour is deteriorating before they reach the high-risk threshold. ## Customer Intelligence Customer Intelligence is an AI-powered layer built on top of Health Scores. While Health Scores give you a numeric snapshot, Customer Intelligence provides natural-language explanations, forward-looking predictions, and actionable recommendations for every customer. ### AI-Powered Narratives Each customer receives an automatically generated narrative that explains their health score in plain English. The narrative summarises payment behaviour, highlights recent changes, and calls out specific risk factors or positive trends. Narratives appear in the **Intelligence Panel** on the customer detail page. You can click **Regenerate** to request a fresh narrative at any time -- useful after a customer makes a large payment or resolves an overdue invoice. ### Payment Failure Predictions RevKeen analyses a 20-feature vector for each customer to predict the likelihood of their next payment failing. Features include: - Recent failure rate and hard-decline history - Payment method age and expiration proximity - Average days to pay and dunning depth - Transaction amount volatility and frequency patterns Each prediction returns a **failure probability** (0--100%), a **risk level** (low, medium, or high), the top contributing **risk factors**, and a **recommended action** such as updating the payment method or switching to manual invoicing. ### Churn Predictions A separate model assesses the probability of each customer churning within the next billing cycle. The churn signal vector includes: - Health score trend direction and velocity - Subscription downgrade or cancellation signals - Payment failure frequency over the last 90 days - Engagement patterns (portal logins, support interactions) Churn predictions include a **churn probability**, **risk level**, **risk signals**, and a **recommended action** to retain the customer. ### Unified Intelligence Panel The customer detail page includes an **Intelligence Panel** that brings together all three outputs: - **Narrative** -- the AI-generated health summary - **Payment risk** -- failure probability, risk level, and top factors - **Churn risk** -- churn probability, risk level, and key signals The panel updates automatically after each scheduled prediction run. ### Intelligence Summary Card The dashboard home page includes an **Intelligence Summary** card that aggregates predictions across all customers: - Average health score and distribution breakdown - Number of customers at risk - Predicted payment failures in the next 7 days - Customers with high churn probability Use this card to quickly identify which customers need attention. ### Prediction Schedule | Prediction | Schedule | Notes | |-----------|----------|-------| | Health narratives | Daily at 03:30 UTC | Runs after health score recalculation | | Payment failure | Daily at 04:00 UTC | Covers all customers with active payment methods | | Churn | Monthly at 05:00 UTC (1st) | Assessed once per billing cycle | All predictions can also be triggered on-demand from the customer detail page. ## Related - [Customers](/docs/using-revkeen/customers) -- Customer profiles, payment methods, and custom fields - [Dunning](/docs/using-revkeen/dunning) -- Automated payment recovery that feeds into health scores - [Customer Portal](/docs/using-revkeen/customer-portal) -- Self-service portal for customers --- # Customer Portal Source: https://docs.revkeen.com/docs/using-revkeen/customer-portal Give customers self-service access to manage subscriptions, invoices, and payment methods The Customer Portal gives your customers a secure place to manage their subscriptions, view invoices, update payment methods, and access purchased content -- all without contacting support. ## What is the Customer Portal? The Customer Portal is a hosted web application where customers can: - View and download invoices with billing interval details (e.g., "Billed monthly") - Manage subscriptions (upgrade, downgrade, cancel) - Update payment methods - Access digital products and downloads - View order history and receipts - Update their profile information ## How Customers Access the Portal Customers can access their portal via: - **Direct link** -- Portal URL with their email - **Email links** -- Links in invoices and receipts - **Magic link** -- Passwordless email login - **Your website** -- Embed a "Manage Subscription" button > The portal uses secure, passwordless authentication. Customers receive a magic link via email to sign in. ## Portal URL Your customer portal is available at: ``` https://checkout.revkeen.com/portal/your-merchant-slug ``` Or with custom domain (if configured): ``` https://billing.yourdomain.com ``` ## Portal Sections | Section | Description | |---------|-------------| | **Dashboard** | Overview of active subscriptions and recent activity | | **Subscriptions** | Manage active and past subscriptions | | **Invoices** | View, download, and pay invoices | | **Payment Methods** | Add, update, or remove payment methods | | **Downloads** | Access digital products and files | | **Profile** | Update personal information | ## Subscription Management Customers can manage their subscriptions directly: | Action | Description | Configurable | |--------|-------------|-------------| | **View subscriptions** | See active and past subscriptions | Always on | | **Upgrade plan** | Switch to higher-priced plan | Yes | | **Downgrade plan** | Switch to lower-priced plan | Yes | | **Change billing cycle** | Switch monthly/annual | Yes | | **Pause subscription** | Temporarily stop billing | Yes | | **Cancel subscription** | End the subscription | Yes | | **Reactivate** | Resume cancelled subscription | Yes | ### Plan Change Options Configure how plan changes work: - **Immediate** -- Change takes effect now with proration - **At period end** -- Change when current period ends - **Customer choice** -- Let customer decide ### Cancellation Flow Customize the cancellation experience: - **Cancellation survey** -- Ask why they're leaving - **Retention offers** -- Offer discounts to stay - **Downgrade suggestion** -- Suggest cheaper plans - **Pause option** -- Offer pause instead of cancel > Thoughtful cancellation flows can reduce churn by 10-30%. ## Invoice Access Customers can manage their invoices: - **View invoices** -- See all past invoices - **Download PDF** -- Get invoice as PDF - **Pay open invoices** -- Pay outstanding balances - **View receipts** -- Access payment receipts ## Payment Method Management Customers can manage their payment methods: | Action | Description | |--------|-------------| | **View cards** | See saved payment methods | | **Add card** | Add a new payment method | | **Set default** | Choose primary payment method | | **Remove card** | Delete saved cards | | **Update expiration** | Update expiring card details | > **Warning:** Customers cannot remove the last payment method if they have an active subscription that requires payment. > The Customer Portal uses **magic link authentication** (full session login) for payment method management. This is separate from the **email OTP verification** used at checkout to access saved cards. Both flows verify email ownership but serve different purposes -- the portal provides full account management, while checkout OTP is a lightweight step-up for a single payment. ## Digital Product Access For products with digital benefits: - **Download files** -- Access purchased downloads - **View license keys** -- See software licenses - **Access links** -- Links to external content - **Download history** -- Track download activity ## Profile Management Customers can update their information: - **Name** -- Update display name - **Email** -- Change email address - **Billing address** -- Update billing details - **Shipping address** -- Update shipping info - **Custom fields** -- Edit custom profile fields ## Notification Preferences Optionally let customers manage email preferences: - Receipt emails - Invoice reminders - Subscription renewal notices - Marketing communications (if applicable) ## Benefits of Self-Service The portal benefits both you and your customers: | For You | For Customers | |---------|--------------| | Reduced support requests | Instant access, no waiting | | Automated payment updates | Update card before it expires | | Lower churn through easy upgrades | Easy plan changes | | 24/7 availability | Access anytime | ## Enabling the Portal The Customer Portal is enabled by default. To configure: 1. Go to **Settings > Customer Portal** 2. Enable or disable portal features 3. Configure which actions customers can take 4. Customize appearance and branding 5. Save settings ## Customization Brand the portal to match your product: - **Logo** -- Display your logo - **Colors** -- Match your brand colors - **Custom domain** -- Use your own domain - **Support links** -- Link to your help center ## Configuring Features Enable or disable features in Settings: 1. Go to **Settings > Customer Portal** 2. Toggle features on or off 3. Configure feature-specific options 4. Save changes Common configurations by business type: | Business Type | Recommended Settings | |--------------|---------------------| | **SaaS** | Full subscription management, plan upgrades | | **E-commerce** | Invoice access, order history, limited sub management | | **Membership** | Full access with pause option | | **B2B** | Invoice focus, restricted cancellation | ## Security Features The portal includes security protections: - **Magic link auth** -- Secure passwordless login - **Session timeout** -- Auto logout after inactivity - **Rate limiting** -- Protection against abuse - **Audit logging** -- Track all customer actions ## Related - [Customers](/docs/using-revkeen/customers) -- Customer data model - [Subscriptions](/docs/using-revkeen/subscriptions) -- Subscription management - [Benefits](/docs/using-revkeen/benefits) -- Digital product delivery --- # Customers Source: https://docs.revkeen.com/docs/using-revkeen/customers Create and manage customer profiles, payment methods, and communication preferences Customers are the foundation of billing operations in RevKeen. Every subscription, invoice, and payment is associated with a customer. Each customer can have multiple payment methods, addresses, subscriptions, and orders associated with them. ## What is a Customer? A Customer record stores: - **Contact information** -- Name, email, phone - **Payment methods** -- Cards, bank accounts for future charges - **Addresses** -- Billing and shipping addresses - **Billing history** -- All invoices, orders, and subscriptions - **Custom fields** -- Additional data you define ## Customer Fields | Field | Type | Required | Description | |-------|------|----------|-------------| | `email` | string | Yes | Primary email address | | `name` | string | No | Full name or business name | | `companyName` | string | No | Business or company name | | `phone` | string | No | Phone number (E.164 format recommended) | | `currency` | string | No | Preferred currency for invoices | | `tax_id` | string | No | Tax identification number (VAT, EIN, etc.) | | `address` | object | No | Billing address | | `metadata` | object | No | Custom key-value pairs | ## Creating Customers ### Automatic Creation Customers are automatically created when: - A new email completes checkout - You create an invoice for a new email - Imported from integrations (PracticeHub, Wodify, etc.) ### Via Dashboard 1. Navigate to **Customer** 2. Click **+ New Customer** 3. Enter email and other details 4. Save the customer ### Via API ```typescript const customer = await client.customers.create({ email: 'john@example.com', name: 'John Smith', phone: '+1-555-123-4567', currency: 'USD', // Optional: Billing address address: { line1: '123 Main St', line2: 'Suite 100', city: 'San Francisco', state: 'CA', postalCode: '94102', country: 'US', }, // Optional: Tax ID for business customers taxId: 'US123456789', // Optional: Custom metadata metadata: { salesRep: 'jane@company.com', tier: 'enterprise', }, }); console.log(customer.data.id); // cus_xxxxxxxx ``` ```python customer = client.customers.create( email="john@example.com", name="John Smith", phone="+1-555-123-4567", currency="USD", # Optional: Billing address address={ "line1": "123 Main St", "line2": "Suite 100", "city": "San Francisco", "state": "CA", "postal_code": "94102", "country": "US" }, # Optional: Tax ID for business customers tax_id="US123456789", # Optional: Custom metadata metadata={ "sales_rep": "jane@company.com", "tier": "enterprise" } ) print(customer.data.id) # cus_xxxxxxxx ``` ## Listing Customers ```typescript // List all customers with pagination const customers = await client.customers.list({ limit: 20, page: 1, }); // Search by email const customers = await client.customers.list({ email: 'john@example.com', }); // Auto-pagination for await (const customer of client.customers.list()) { console.log(customer.email); } ``` ## Updating Customers ```typescript const customer = await client.customers.update('cus_xxxxxxxx', { name: 'John Smith', metadata: { plan: 'pro', upgraded_at: new Date().toISOString(), }, }); ``` ## Deleting Customers ```typescript // Soft delete - marks customer as deleted but retains data await client.customers.delete('cus_xxxxxxxx'); ``` > Deleting a customer cancels all active subscriptions and prevents new charges. Historical data is retained for compliance. ## Business Customers (B2B) For B2B billing, you can associate customers with a business entity: - **Business name** -- Legal entity name - **Tax ID** -- VAT number, EIN, etc. - **Business address** -- Separate from individual address > Enable business checkout in your checkout link settings to collect business information during purchase. ## Payment Methods Customers can have multiple saved payment methods: | Type | Description | Supported | |------|-------------|-----------| | Card | Credit/debit cards (Visa, Mastercard, Amex, etc.) | Yes | | ACH | US bank accounts (ACH Direct Debit) | Yes | | SEPA | European bank accounts | Coming soon | Payment methods are securely tokenized by your payment gateway. RevKeen never stores raw card numbers. ### Default Payment Method One payment method can be marked as default. This is automatically used for: - Subscription renewals - Auto-pay invoices - Retry attempts during dunning ### Saved Card Security at Checkout When a customer returns to checkout and has saved cards, they must verify their identity before accessing them. This is done via a 6-digit email verification code (or automatically if they have a trusted device cookie from a previous verification). Additionally, customers must re-enter their card's CVV for every saved card payment. See the [Checkout](/docs/using-revkeen/checkout) page for details. ## Addresses Customers can have multiple addresses with different types: | Address Type | Used For | |-------------|----------| | Billing | Invoice "Bill To" address, tax calculations | | Shipping | Physical product delivery | ## Custom Fields Extend customer data with custom fields defined in **Settings > Custom Fields**: - Text fields (IDs, notes) - Numbers (account numbers, scores) - Dates (birthdays, contract dates) - Dropdowns (status, category) - Checkboxes (preferences, consent) ## Health Scores and Intelligence RevKeen automatically calculates a health score (0--100) for each customer and uses AI to predict payment failures and churn risk. See [Customer Health Scores](/docs/using-revkeen/customer-health-scores) for details. ## Customer Portal Customers can self-manage their account through the Customer Portal: - View and pay invoices - Download invoice PDFs - Update payment methods - Manage subscriptions (pause, cancel) - View billing history The Customer Portal is available at `checkout.revkeen.com/portal/[your-slug]`. You can also create a portal session programmatically to let customers manage their own billing: ```typescript const portal = await client.billingPortal.sessions.create({ customerId: 'cus_xxxxxxxx', returnUrl: 'https://yourapp.com/account', }); // Redirect customer to portal return redirect(portal.data.url); ``` ## Customer Events | Event | When Triggered | |-------|---------------| | `customer.created` | Customer record is created | | `customer.updated` | Customer details are modified | | `customer.payment_method.attached` | Payment method is added | | `customer.payment_method.detached` | Payment method is removed | ## Related - [Subscriptions](/docs/using-revkeen/subscriptions) -- Create subscriptions for customers - [Invoices and Orders](/docs/using-revkeen/invoices-and-orders) -- Send invoices to customers - [Customer Portal](/docs/using-revkeen/customer-portal) -- Self-service portal for customers - [Dunning](/docs/using-revkeen/dunning) -- Automated payment recovery that feeds into health scores --- # Disputes Source: https://docs.revkeen.com/docs/using-revkeen/disputes Handle chargebacks, respond to disputes, and prevent future occurrences A dispute (chargeback) occurs when a customer contests a charge with their bank. RevKeen tracks disputes automatically and helps you respond with the right evidence to protect your revenue. ## What is a Dispute? When a cardholder contacts their bank to reverse a charge, the bank initiates a dispute. The funds are temporarily held while both sides present evidence. RevKeen notifies you immediately and provides tools to respond. ## Dispute Lifecycle | Status | Description | Action Required | |--------|-------------|-----------------| | `open` | Dispute received, evidence window open | Submit evidence before deadline | | `under_review` | Evidence submitted, bank reviewing | Wait for bank decision | | `won` | Dispute resolved in your favor | Funds returned to you | | `lost` | Dispute resolved in customer's favor | Funds returned to customer | ## Common Dispute Reasons | Reason | Description | Best Response | |--------|-------------|---------------| | **Fraudulent** | Customer claims they did not authorize the charge | Provide proof of authorization, delivery confirmation, IP address logs | | **Product Not Received** | Customer says they never received the product or service | Provide delivery tracking, access logs, or proof of service completion | | **Not as Described** | Product or service did not match what was advertised | Provide product description, terms of service, correspondence | | **Duplicate Charge** | Customer charged multiple times for the same item | Show distinct invoices for each charge, or issue refund if duplicate | | **Subscription Canceled** | Customer claims they canceled but were still charged | Provide cancellation policy, subscription status history | ## Responding to Disputes When you receive a dispute notification: 1. **Review the dispute details** -- Go to Finance > Disputes in the dashboard to see the dispute reason, amount, and deadline. 2. **Gather evidence** -- Collect relevant documentation: invoices, delivery confirmations, customer communications, terms of service, and transaction records. 3. **Submit your response** -- Upload evidence and provide a clear explanation before the deadline (typically 7-21 days). 4. **Wait for resolution** -- The bank reviews evidence from both sides. Decisions typically take 30-90 days. > **Warning:** Missing the evidence deadline automatically results in a lost dispute. Set up webhook notifications to ensure you never miss a deadline. ## Preventing Disputes - **Clear Descriptors** -- Use recognizable business names in statement descriptors so customers know who charged them. - **Transparent Pricing** -- Clearly display all charges, including taxes and fees, before checkout. Recurring billing intervals are shown on invoices and receipts. - **Easy Cancellation** -- Make it simple for customers to cancel subscriptions through the customer portal rather than disputing charges. - **Prompt Communication** -- Respond quickly to customer inquiries about charges. Many disputes can be resolved before they reach the bank. > RevKeen's Customer Portal lets customers view invoices, manage subscriptions, and download receipts -- reducing "I don't recognize this charge" disputes significantly. ## Dispute Webhooks | Event | Description | |-------|-------------| | `payment.disputed` | New dispute received | | `dispute.won` | Dispute resolved in your favor | | `dispute.lost` | Dispute resolved in customer's favor | > RevKeen sends in-app notifications and optional email alerts when disputes are received, so you can respond quickly. ## Related - [Payments and Refunds](/docs/using-revkeen/payments-and-refunds) -- Processing payments and issuing refunds - [Customer Portal](/docs/using-revkeen/customer-portal) -- Self-service access reduces disputes - [Disputes (Reporting)](/docs/money/disputes) -- Dispute metrics, financial impact, and prevention tracking --- # Dunning Source: https://docs.revkeen.com/docs/using-revkeen/dunning Recover failed payments automatically with smart retry schedules and customer notifications When a subscription payment fails, RevKeen automatically enters a dunning process that intelligently retries payments while keeping your customers informed. This process typically recovers 30-50% of failed payments without any manual intervention. ## How Dunning Works When a payment fails, RevKeen classifies the decline code and determines the best recovery strategy: 1. **Classify Decline** -- Analyze the decline code to determine if it's a temporary (soft) or permanent (hard) decline. 2. **Smart Retry** -- Schedule automatic retries based on decline type. Soft declines get retried on Days 1, 3, and 7. 3. **Notify Customer** -- Send targeted emails at each stage to encourage customers to update their payment method. ## Decline Code Categories | Category | Description | Action | Example Codes | |----------|-------------|--------|--------------| | **Hard Decline** | Card permanently blocked or invalid | No retry -- request new card | 200, 204, 303, 530, 531 | | **Soft Decline** | Temporary issue (insufficient funds, etc.) | Auto-retry on schedule | 300, 301, 304, 402, 521 | | **Action Required** | Customer must update card | Email customer to update | 202, 223, 225 | ## Default Retry Schedule The default retry schedule balances recovery rates with customer experience: | Day | Action | Email Sent | Service Access | |-----|--------|-----------|----------------| | **Day 0** | Payment fails, subscription enters `past_due` | "Payment Failed" | Full access | | **Day 1** | First retry attempt | None (if successful) / "Retry Failed" | Full access | | **Day 3** | Second retry attempt | "Urgent: Update Payment Method" | Warning shown | | **Day 7** | Final retry attempt | "Service Suspended" (if failed) | Suspended | > You can customize the retry schedule and grace period in your merchant settings. Longer grace periods may recover more payments but also increase revenue delay. ## Grace Period Configuration The grace period determines how long customers retain access while their payment is being retried. Configure these settings per-merchant: | Setting | Description | Default | |---------|-------------|---------| | `grace_period_days` | Days before service suspension | 7 | | `max_retry_attempts` | Maximum payment retry attempts | 3 | | `retry_schedule` | Days between retries | [1, 3, 7] | | `dunning_email_enabled` | Send dunning emails | true | | `auto_cancel_unpaid` | Cancel after max retries exhausted | false | ## Dunning Email Sequence RevKeen sends a series of emails to help customers recover their subscription: **Day 0: Payment Failed** -- "We couldn't charge your card. Please update your payment method to avoid service interruption." **Day 1: Retry Failed** -- "Still having trouble charging your card. We'll retry again soon, but please update your payment method." **Day 3: Urgent Action Needed** -- "Action needed to avoid service interruption. Update your payment method now." **Day 7: Service Suspended** -- "Your subscription has been suspended due to payment failure. Update your payment method to restore access." ## Subscription States During Dunning | State | Description | Service Access | |-------|-------------|----------------| | `past_due` | Payment failed, in grace period with retries scheduled | Limited | | `unpaid` | All retries exhausted, service suspended | None | | `canceled` | Terminated after dunning (if auto_cancel_unpaid=true) | None | > When `auto_cancel_unpaid` is set to `true`, the subscription will automatically cancel after all retries are exhausted. Otherwise, it remains in `unpaid` status until manually resolved. ## Handling Dunning via API While dunning is automatic, you can interact with it programmatically. ### Check Subscription Dunning Status ```typescript const subscription = await client.subscriptions.retrieve('sub_xxxxxxxx'); if (subscription.data.status === 'past_due') { console.log('Subscription is in dunning'); console.log('Grace period ends:', subscription.data.current_period_end); } if (subscription.data.status === 'unpaid') { console.log('All retries exhausted - needs manual intervention'); } ``` ```python subscription = client.subscriptions.retrieve("sub_xxxxxxxx") if subscription.data.status == "past_due": print("Subscription is in dunning") print(f"Grace period ends: {subscription.data.current_period_end}") if subscription.data.status == "unpaid": print("All retries exhausted - needs manual intervention") ``` ### Manually Retry a Failed Payment ```typescript // Get the past-due invoice const invoices = await client.invoices.list({ subscription: 'sub_xxxxxxxx', status: 'past_due', }); // Manually retry payment const result = await client.invoices.pay(invoices.data[0].id); if (result.data.status === 'paid') { console.log('Payment recovered successfully!'); } ``` ```python # Get the past-due invoice invoices = client.invoices.list( subscription="sub_xxxxxxxx", status="past_due" ) # Manually retry payment result = client.invoices.pay(invoices.data[0].id) if result.data.status == "paid": print("Payment recovered successfully!") ``` ## Dunning Webhooks Listen to these webhooks to stay informed about dunning progress: ### Subscription & Invoice Events | Event | Description | |-------|-------------| | `invoice.payment_failed` | Payment attempt failed | | `invoice.payment_action_required` | Customer action needed (e.g., 3DS verification) | | `subscription.past_due` | Subscription entered past_due status | | `subscription.unpaid` | All retries exhausted | | `invoice.paid` | Payment recovered | | `invoice.marked_uncollectible` | Invoice written off as bad debt | ### Dunning Lifecycle Events These events provide granular visibility into the dunning process: | Event | Description | |-------|-------------| | `dunning.case_started` | First retry scheduled -- new dunning case opened | | `dunning.step_executed` | Retry attempt completed (includes `metadata.outcome`: `success` or `failed`) | | `dunning.phase_escalated` | Dunning phase changed (e.g., Initial Retry → Warning → Final Notice) | | `dunning.exhausted` | All retries exhausted, exhaustion action applied | | `dunning.completed` | Payment recovered, dunning case closed | > Subscribe to all dunning events using the `dunning.*` glob pattern. ### Webhook Handler Example ```typescript app.post('/webhooks/revkeen', async (req, res) => { const event = req.body; switch (event.type) { case 'invoice.payment_failed': // Log failed payment, maybe trigger internal notification console.log('Payment failed for invoice:', event.data.id); break; case 'dunning.case_started': // Proactive customer outreach await notifySupport(event.data.subscriptionId, event.data.customerEmail); break; case 'dunning.exhausted': // Suspend service access await suspendAccess(event.data.subscriptionId); break; case 'dunning.completed': // Payment recovered! Restore access await restoreAccess(event.data.subscriptionId); break; case 'invoice.paid': // Invoice paid (may also trigger for non-dunning payments) await restoreAccess(event.data.customer_id); break; } res.status(200).send('OK'); }); ``` ## Best Practices - **Keep Cards Updated** -- Encourage customers to enable card updates with their bank. Use the `customer.update_payment_method` webhook to prompt updates before expiration. - **Grace Period Length** -- 7 days is the sweet spot for most businesses -- long enough to recover payments, short enough to minimize revenue lag. - **Custom Retry Schedule** -- For high-value subscriptions, consider extending retries to 14 days with more attempts. For low-value, shorter schedules reduce bad debt. - **Monitor Recovery Rates** -- Track your dunning recovery rate in analytics. Aim for 30-50% recovery of failed payments. Below 20% may indicate card quality issues. > **Warning:** Never disable dunning emails completely. They are proven to significantly improve recovery rates and reduce involuntary churn. ## Related - [Subscriptions](/docs/using-revkeen/subscriptions) -- Learn about the full subscription lifecycle - [Payments and Refunds](/docs/using-revkeen/payments-and-refunds) -- Processing payments and issuing refunds --- # Invoices and Orders Source: https://docs.revkeen.com/docs/using-revkeen/invoices-and-orders Send invoices, manage one-time orders, and track payment status Invoices represent payment requests sent to customers. RevKeen automatically creates invoices for subscriptions, but you can also create manual invoices for one-time charges. Orders are fulfillment containers created when invoices with deliverable products are paid. ## Invoice Lifecycle ``` ┌─────────┐ ┌──────────────────┐ ┌──────────┐ ┌──────┐ │ DRAFT │────>│ PENDING_APPROVAL │────>│ APPROVED │────>│ SENT │ └─────────┘ └──────────────────┘ └──────────┘ └──┬───┘ │ ┌───────────────────────────────────┘ │ v ┌─────────────────────┐ │ AWAITING PAYMENT │ └──────────┬──────────┘ │ ┌───────────────┼───────────────┐ │ │ │ v v v ┌───────────┐ ┌───────────┐ ┌─────────┐ │ PAID │ │ PARTIALLY │ │ OVERDUE │ │ │ │ PAID │ │ │ └───────────┘ └───────────┘ └─────────┘ ``` ## Invoice Statuses | Status | Description | Available Actions | |--------|-------------|-------------------| | `draft` | Being prepared, fully editable | Edit, add items, delete, submit | | `pending_approval` | Submitted for internal review | Approve, reject, edit | | `approved` | Ready to send to customer | Send, void | | `sent` | Delivered to customer | Resend, record payment, void | | `partially_paid` | Some payment received | Record payment, send reminder | | `paid` | Fully paid | Issue refund | | `overdue` | Past due date, unpaid | Send reminder, void | | `voided` | Cancelled | None | | `refunded` | Payment returned | None | | `uncollectible` | Written off as bad debt | None | ## Invoice Types ### Manual Invoices Created by you through the dashboard or API. Use for custom charges, consulting fees, one-time services, or any billing that doesn't fit a subscription model. ### Subscription Invoices Automatically generated at each billing period. Includes subscription items and any usage charges. Payment is attempted automatically using the customer's saved payment method. Each line item includes the billing interval (e.g., "Billed monthly") so customers always know their recurring schedule. ### Checkout Invoices Created when a customer completes a checkout. If the checkout contains products with physical or digital fulfillment, an order is also automatically created when the invoice is paid. ## Creating Invoices ```typescript const invoice = await client.invoices.create({ customerId: 'cus_xxxxxxxx', currency: 'USD', dueDate: '2026-03-15T00:00:00Z', // Line items lineItems: [ { description: 'Consulting - February 2026', amountMinor: 50000, // $500.00 quantity: 1, }, { description: 'Travel expenses', amountMinor: 15000, // $150.00 quantity: 1, }, ], // Optional memo: 'Thank you for your business!', footer: 'Payment due within 30 days.', }); console.log(invoice.data.invoiceNumber); // INV-2026-0001 ``` ```python invoice = client.invoices.create( customer_id="cus_xxxxxxxx", currency="USD", due_date="2026-03-15T00:00:00Z", line_items=[ { "description": "Consulting - February 2026", "amount_minor": 50000, "quantity": 1, }, { "description": "Travel expenses", "amount_minor": 15000, "quantity": 1, }, ], memo="Thank you for your business!", footer="Payment due within 30 days." ) print(invoice.data.invoice_number) # INV-2026-0001 ``` ## Sending Invoices ```typescript // Finalize the invoice (moves from draft to approved/sent) const invoice = await client.invoices.finalize('inv_xxxxxxxx'); // Send via email await client.invoices.send('inv_xxxxxxxx', { to: ['john@example.com', 'billing@example.com'], cc: ['accountant@yourcompany.com'], }); ``` > The invoice email includes a secure payment link where customers can view and pay online. ## Adding Line Items ```typescript // Add a line item to a draft invoice await client.invoices.addLineItem('inv_xxxxxxxx', { description: 'Additional service', amountMinor: 25000, quantity: 1, }); // Add from a product await client.invoices.addLineItem('inv_xxxxxxxx', { productId: 'prod_xxxxxxxx', quantity: 2, }); ``` ## Recording Payments For payments made outside of RevKeen (cash, check, bank transfer): ```typescript // Record an external payment await client.invoices.pay('inv_xxxxxxxx', { amountMinor: 65000, paymentMethod: 'cash', note: 'Paid via check #1234', }); // Or pay with a saved card await client.invoices.pay('inv_xxxxxxxx', { paymentMethodId: 'pm_xxxxxxxx', }); ``` ## Approval Workflow For businesses requiring review before sending invoices: 1. Create invoice as draft 2. Click **Submit for Approval** 3. Approver reviews the invoice 4. **Approves** -- Invoice moves to "Approved" status 5. Or **Rejects** -- Invoice returns to "Draft" with notes 6. Send the approved invoice to the customer ## Voiding Invoices ```typescript // Void an unpaid invoice await client.invoices.void('inv_xxxxxxxx', { reason: 'Duplicate invoice', }); ``` > **Warning:** Paid invoices cannot be voided. Use refunds instead to return payment. ## Subscription Invoices RevKeen automatically creates invoices for subscriptions: - Created at start of each billing period - Automatically finalized and charged - Past due invoices trigger dunning emails - Failed payments retry according to your retry schedule ```typescript // List invoices for a subscription const invoices = await client.invoices.list({ subscriptionId: 'sub_xxxxxxxx', }); ``` ## Invoice Best Practices 1. **Clear line item descriptions** -- Customers should understand exactly what they're being charged for. 2. **Reasonable due dates** -- 14-30 days is typical; adjust based on your industry. 3. **Follow up promptly** -- Send reminders for overdue invoices within a few days. 4. **Use the approval workflow** -- For large invoices, get internal review before sending. 5. **Add helpful notes** -- Use memo and footer fields for payment instructions or thank you messages. --- ## Invoice Line Items Invoice Line Items represent individual charges on an invoice. Each line item tracks where it came from (its source), enabling accurate revenue attribution and audit trails. ### What is a Line Item? A line item is a single entry on an invoice that describes a specific charge. Each line item has: - **Description** -- What the charge is for - **Amount** -- How much is being charged - **Quantity** -- Number of units - **Source Type** -- Where the line item originated - **Source Reference** -- Link to the originating entity ### Source Types Line items can originate from different sources, tracked by the `source_type` field: | Source Type | Description | When Used | |------------|-------------|-----------| | `price` | From a product price in your catalog | Manual invoices referencing products | | `subscription_item` | From a subscription item | Subscription invoices | | `order_line_item` | From an order | Order invoices | | `adjustment` | Manual adjustment or custom charge | Credits, discounts, corrections, custom fees | ### Line Item Fields | Field | Type | Description | |-------|------|-------------| | `description` | string | Human-readable description of the charge | | `amount_minor` | integer | Unit price in minor units (cents) | | `quantity` | integer | Number of units | | `total_minor` | integer | amount_minor x quantity | | `source_type` | enum | price, subscription_item, order_line_item, adjustment | | `source_id` | string | ID of the source entity | | `tax_amount_minor` | integer | Tax amount for this line item | | `billing_interval` | string | Billing interval for recurring items: `day`, `week`, `month`, `quarter`, `half_year`, `year` | | `billing_interval_count` | integer | Number of intervals between charges (default 1) | | `period_start` | datetime | Billing period start (subscriptions) | | `period_end` | datetime | Billing period end (subscriptions) | ### Adding Line Items #### From a Product Price ```typescript await client.invoices.addLineItem('inv_xxxxxxxx', { priceId: 'price_xxxxxxxx', quantity: 2, }); // Creates line item with source_type: 'price' ``` #### Custom Line Item (Adjustment) ```typescript await client.invoices.addLineItem('inv_xxxxxxxx', { description: 'Rush delivery fee', amountMinor: 5000, // $50.00 quantity: 1, }); // Creates line item with source_type: 'adjustment' ``` #### Credit / Discount Line Item ```typescript await client.invoices.addLineItem('inv_xxxxxxxx', { description: 'Loyalty discount - 10%', amountMinor: -2500, // -$25.00 credit quantity: 1, }); ``` ### Billing Interval on Line Items For recurring items, the billing interval is stored directly on the line item as a snapshot from the product or subscription at the time of creation. This ensures invoices and receipts always show the correct billing frequency, even if the product is later changed. The billing interval is displayed on: - Invoice PDFs (below the line item description, e.g., "Billed monthly") - Payment receipts - Public invoice pages (guest view) - Dashboard invoice preview > For invoices created before the billing interval feature, RevKeen automatically looks up the interval from the linked product as a fallback. ### Automatic Line Items Some line items are created automatically: - **Subscription Renewals** -- When a subscription renews, line items are automatically created from each subscription item. The `period_start` and `period_end` fields indicate the billing period covered, and the `billing_interval` shows the recurring frequency. - **Checkout Completions** -- When a customer completes checkout, order line items become invoice line items with `source_type: order_line_item`. - **Prorations** -- When a subscription changes mid-cycle, prorated adjustments are added as line items to credit unused time or charge for upgrades. ### Why Source Tracking Matters 1. **Revenue Attribution** -- Know exactly which products and subscriptions are generating revenue. 2. **Audit Trail** -- Trace any charge back to its origin for compliance and reconciliation. 3. **Refund Processing** -- Refund specific line items rather than entire invoices. 4. **Reporting** -- Generate accurate reports by product, subscription, or customer. > Line items cannot be modified after an invoice is finalized. To make changes, void the invoice and create a new one. --- ## Orders Orders are fulfillment containers in RevKeen. When an invoice containing products with a `fulfillment_type` of `physical` or `digital` is paid, an Order is automatically created to track delivery. This applies to both one-time purchases and recurring subscription renewals. ### What is an Order? An Order is a fulfillment container that tracks the delivery of products. Unlike invoices (which track the commercial/financial side), orders track the physical or digital delivery of goods. Orders are created automatically when an invoice containing fulfillable items is paid. > Products in RevKeen have two dimensions: **billing type** (one_time or recurring) and **fulfillment type** (none, physical, or digital). Orders are created for any product where fulfillment_type is not "none", regardless of billing type. Orders are created from: - Invoice payment (when invoice contains fulfillable products) - Subscription renewals (for recurring products with physical/digital fulfillment) - Checkout link completions (for products with fulfillment) - Direct API calls - Manual creation in the dashboard ### Invoice vs Order | Aspect | Invoice | Order | |--------|---------|-------| | Purpose | Commercial truth -- what was charged | Fulfillment truth -- what needs delivering | | Created for | Every purchase (one-time and recurring) | Only products with physical or digital fulfillment | | Tracks | Amounts, taxes, discounts, payments | Shipping, tracking numbers, delivery status | | Recurring | New invoice each billing period | New order each renewal (if fulfillable items exist) | ### Order Statuses | Status | Description | |--------|-------------| | `draft` | Order created but not yet confirmed | | `pending` | Order confirmed, awaiting payment | | `partially_paid` | Partial payment received | | `paid` | Payment received, ready for fulfillment | | `partially_fulfilled` | Some items shipped/delivered | | `fulfilled` | All items shipped/delivered | | `canceled` | Order cancelled | | `refunded` | Payment refunded | ### Order Line Items Each order contains one or more line items representing products purchased: | Field | Description | |-------|-------------| | `product_id` | Reference to the product | | `price_id` | Reference to the price used | | `quantity` | Number of units ordered | | `amount_minor` | Total price for this line item | | `fulfillment_status` | pending, shipped, delivered | ### Fulfillment Tracking Fulfillment tracking depends on the product's `fulfillment_type`: **Physical Products** -- Track shipping status, carrier, and tracking numbers. Flow: pending -> shipped -> delivered. **Digital Products** -- Typically fulfilled immediately with download links or access granted. Flow: pending -> delivered (automatic). **No Fulfillment (fulfillment_type: none)** -- Products with no fulfillment type (e.g., SaaS subscriptions, memberships) do not create orders. The invoice alone tracks the purchase. ### Creating Orders via API ```typescript const order = await client.orders.create({ customerId: 'cus_xxxxxxxx', currency: 'USD', lineItems: [ { priceId: 'price_xxxxxxxx', quantity: 2, }, { priceId: 'price_yyyyyyyy', quantity: 1, }, ], // Optional: Apply a discount discountId: 'disc_xxxxxxxx', // Optional: Shipping address (for physical products) shippingAddress: { line1: '123 Main St', city: 'San Francisco', state: 'CA', postalCode: '94102', country: 'US', }, }); console.log(order.data.id); // ord_xxxxxxxx ``` ### Managing Orders in Dashboard Navigate to **Sales > Orders** to: - View all orders with filtering by status, date, customer - Click an order to view details and line items - Update fulfillment status for physical products - Add tracking information for shipments - Process refunds for paid orders - Cancel pending orders ### Order Events | Event | When Triggered | |-------|---------------| | `order.created` | Order is created | | `order.paid` | Payment is received | | `order.fulfilled` | Order is fully fulfilled | | `order.partially_fulfilled` | Some items are fulfilled | | `order.canceled` | Order is cancelled | ## Related - [Customers](/docs/using-revkeen/customers) -- Customer profiles and billing info - [Subscriptions](/docs/using-revkeen/subscriptions) -- How subscriptions generate invoices - [Payments and Refunds](/docs/using-revkeen/payments-and-refunds) -- Handle invoice payments --- # Payments and Refunds Source: https://docs.revkeen.com/docs/using-revkeen/payments-and-refunds Process payments, issue refunds, manage credit notes, and handle multi-gateway reversals RevKeen processes payments through your connected payment gateway, handling tokenization, authorization, capture, and refunds. This guide covers the complete payment flow, refund processing, credit notes, and best practices. ## Supported Payment Methods - **Credit/Debit Cards** -- Visa, Mastercard, American Express, Discover, and more - **ACH Bank Transfer** -- Direct bank debits for US customers (lower fees) - **Saved Cards** -- Securely stored payment methods for returning customers (email verification + CVV required) ## Payment Flow RevKeen uses tokenization to ensure card data never touches your servers: 1. **Tokenization** -- Customer enters card in secure form; token generated client-side. 2. **Authorization** -- RevKeen verifies the card can be charged for the requested amount. 3. **Capture** -- Funds are captured and transferred (usually immediate). 4. **Confirmation** -- Customer receives receipt, subscription/invoice updated. ## Processing Payments via API ### Create a One-Time Payment ```typescript const payment = await client.payments.create({ customerId: 'cus_xxxxxxxx', amount: 9900, // $99.00 in cents currency: 'USD', paymentMethodToken: 'tok_xxxxxxxx', description: 'Consulting fee', metadata: { orderId: 'order_12345', }, }); if (payment.data.status === 'succeeded') { console.log('Payment successful!'); console.log('Transaction ID:', payment.data.transactionId); } ``` ```python payment = client.payments.create( customer_id="cus_xxxxxxxx", amount=9900, currency="USD", payment_method_token="tok_xxxxxxxx", description="Consulting fee", metadata={ "order_id": "order_12345" } ) if payment.data.status == "succeeded": print("Payment successful!") print(f"Transaction ID: {payment.data.transaction_id}") ``` ### Pay an Invoice ```typescript // Pay an existing invoice with saved payment method const result = await client.invoices.pay('inv_xxxxxxxx'); // Or specify a different payment method const result = await client.invoices.pay('inv_xxxxxxxx', { paymentMethodId: 'pm_xxxxxxxx', }); console.log('Invoice paid:', result.data.paidAt); ``` ## Transaction Statuses | Status | Description | Funds | |--------|-------------|-------| | `pending` | Payment initiated, awaiting processing | Held | | `succeeded` | Payment completed successfully | Captured | | `failed` | Payment declined or error occurred | None | | `requires_action` | Additional verification needed (3DS) | Held | | `refunded` | Full amount returned to customer | Returned | | `partially_refunded` | Partial amount returned | Partial | | `voided` | Reversed before settlement | Released | ## Handling Declines When a payment fails, RevKeen provides detailed decline information: | Category | Common Codes | Recommended Action | |----------|-------------|-------------------| | **Insufficient Funds** | 300, 301 | Ask customer to use different card or try later | | **Card Declined** | 200, 204 | Card blocked by issuer -- request new card | | **Invalid Card** | 303, 530 | Card number invalid -- re-enter card details | | **Expired Card** | 202, 223 | Request updated card information | | **CVV Mismatch** | 225 | Re-enter CVV -- potential fraud indicator | | **Limit Exceeded** | 402, 521 | Card limit reached -- try smaller amount or different card | ```typescript try { const payment = await client.payments.create({ customerId: 'cus_xxxxxxxx', amount: 9900, currency: 'USD', paymentMethodToken: 'tok_xxxxxxxx', }); } catch (error) { if (error.code === 'payment_declined') { console.log('Decline code:', error.declineCode); console.log('Message:', error.message); switch (error.declineCode) { case '300': case '301': return 'Insufficient funds. Please try a different card.'; case '200': return 'Card declined. Please contact your bank.'; default: return 'Payment failed. Please try again.'; } } } ``` ## 3D Secure (3DS) Authentication Some payments require additional verification through 3D Secure. RevKeen handles this automatically in the checkout flow: 1. Payment initiated -- Gateway determines 3DS is required 2. Customer redirected to bank's verification page 3. Customer completes verification (password, SMS code, etc.) 4. Customer redirected back -- Payment completes > 3DS helps reduce fraud and shifts liability to the card issuer. It's required for Strong Customer Authentication (SCA) in the EU. ## Reversing Payments: Void vs Refund RevKeen provides intelligent payment reversal options based on settlement timing. Understanding when to use each method can save you significant processing fees. ### How It Works | Method | Timing | Processing Fees | Customer Impact | |--------|--------|----------------|-----------------| | **Void** | Before daily settlement (typically before 8 PM ET) | No fees | Charge never appears on statement | | **Refund** | After daily settlement | Original fees not returned | Shows as separate refund transaction | ### Settlement Timing and Smart Warnings RevKeen automatically tracks settlement timing for each payment gateway and provides real-time warnings to help you choose the best reversal method. **Safe to Void** -- Settlement is 2+ hours away. Void will succeed with high confidence. This is the recommended option to avoid processing fees. **High-Risk Void Window** -- Settlement is within 15 minutes. The batch may have already closed. If void fails, you will need to process a refund instead. The dashboard will show "Attempt Void" with a warning alert. **Settlement Complete** -- Transaction has been settled. Void is no longer available. You must process a refund to return funds to the customer. > **Smart Reversal Logic:** RevKeen automatically determines eligibility based on your gateway's settlement schedule. When you view a payment, you'll see only the available options with clear warnings for high-risk scenarios. ### Using the Dashboard 1. **Navigate to Invoice or Payment** -- Go to Invoices, select invoice, click payment row actions menu. 2. **Choose Reversal Method** -- The dialog will show available options based on settlement status. Review settlement timing information and any warnings displayed. 3. **Confirm and Execute** -- Click the action button ("Void Payment", "Attempt Void", or "Process Refund") to execute the reversal. > **Important:** If a high-risk void fails because settlement already occurred, you will need to manually process a refund. The system cannot automatically fall back to refund due to accounting and tax implications. ## Processing Refunds ```typescript // Full refund const refund = await client.refunds.create({ transactionId: 'txn_xxxxxxxx', }); // Partial refund const partialRefund = await client.refunds.create({ transactionId: 'txn_xxxxxxxx', amount: 2500, // Refund $25.00 }); // Refund with reason const refund = await client.refunds.create({ transactionId: 'txn_xxxxxxxx', reason: 'Customer request', }); ``` ```python # Full refund refund = client.refunds.create( transaction_id="txn_xxxxxxxx" ) # Partial refund partial_refund = client.refunds.create( transaction_id="txn_xxxxxxxx", amount=2500 ) # Refund with reason refund = client.refunds.create( transaction_id="txn_xxxxxxxx", reason="Customer request" ) ``` > Refunds typically take 5-10 business days to appear on the customer's statement. You cannot refund more than the original transaction amount. ## Credit Notes Credit notes are RevKeen's **single reversal document**. Instead of separate void, refund, and credit workflows, merchants issue credit notes against a paid invoice and RevKeen automatically routes the correct gateway operation (void, refund, terminal reversal, bank payout) based on the original payment's gateway, payment method, and context. A credit note is always issued against a specific invoice -- it is the formal accounting record that reduces or reverses the amount owed on that invoice. ### When to Use Credit Notes - **Invoice Corrections** -- Wrong amount charged, billing error, or service not delivered as promised. - **Service Credits** -- Goodwill credits, promotional adjustments, or compensation for service issues. - **Subscription Cancellations** -- Prorate refunds when canceling subscriptions mid-period. - **Partial Refunds** -- Return a portion of the invoice amount while keeping the invoice active. - **Voiding Unpaid Invoices** -- A full credit note on an unpaid invoice automatically voids it. ### Creating Credit Notes from the Dashboard There are two ways to issue a credit note: **From an Invoice** (most common): 1. Go to **Invoices** and open a paid invoice. 2. Click **Issue Credit Note** in the invoice actions. 3. Choose full or partial amount, select a reason, and pick a credit method. **From the Customer page:** 1. Go to **Customers** and open a customer. 2. Switch to the **Credit Notes** tab. 3. Click **Issue Credit Note** -- this shows a list of the customer's paid invoices. 4. Select the invoice you want to credit. 5. Fill in the credit note details (amount, reason, credit method). The Credit Notes tab also displays all existing credit notes for that customer with their current status (Processing, Refunded, Failed). ### Credit Note Options | Credit Method | Effect | Best For | |--------------|--------|----------| | **Refund to Payment Method** | Issues credit note and automatically processes the correct gateway reversal | Customer paid and wants money back | | **Customer Balance** | Issues credit note and adds credit to customer account | Customer wants credit toward future purchases | | **Credit Note Only** | Issues credit note for record-keeping only | Manual refund outside RevKeen or goodwill gesture | ### Automatic Gateway Routing When you select "Refund to Payment Method", you do **not** choose which gateway to use. RevKeen automatically determines the correct reversal operation based on how the original payment was made. The routing is fully automatic -- the system reads the payment's gateway from the transaction record and selects the best operation. | Original Payment Method | What RevKeen Does Automatically | |------------------------|--------------------------------| | **Card (online via NMI)** | Void (if pre-settlement) or refund (if post-settlement) | | **Card (terminal / PAX)** | Terminal reversal (same-day), terminal refund (card re-present), or NMI gateway-direct fallback if terminal is offline | | **Bank transfer (fire.com)** | Cancel (if pending) or credit transfer payout to customer IBAN (if settled) | | **Customer balance** | Instant ledger reversal (no gateway call needed) | For terminal payments, RevKeen checks whether the terminal is reachable and whether the customer is present before choosing between a terminal-native reversal and a gateway-direct fallback. If the terminal is offline, the refund is processed through the payment processor without requiring the terminal. > **You don't pick NMI vs Terminal vs Bank.** RevKeen knows how the customer originally paid and routes accordingly. For invoices paid with multiple payments across different gateways, each payment is reversed through its own original gateway. ### Multi-Payment Invoices (LIFO Allocation) When an invoice was paid with multiple payments (for example, a partial card payment and a balance payment), RevKeen allocates the credit in **last-in, first-out (LIFO)** order. The most recent payment is reversed first, then the next most recent, until the full credit amount is allocated. Each payment is reversed through its own original gateway. ### Multiple Credit Notes per Invoice You can issue multiple credit notes against the same invoice. RevKeen validates that the total credited amount never exceeds the invoice total. When credit notes sum to the full invoice amount, the invoice is automatically marked as voided. ### Intelligent Tax Handling RevKeen automatically calculates proportional tax adjustments when issuing credit notes: - **Proportional Tax Credits** -- Tax amounts are automatically calculated proportionally to the credited amount. For example, crediting 50% of an invoice also credits 50% of the tax. - **Penny-Perfect Chain Handling** -- When issuing multiple credit notes against the same invoice, the final credit note automatically "sweeps" any remaining fractional pennies of tax. This prevents 1-2 cent discrepancies that can occur with rounding in credit note chains. - **Tax Provider Sync** -- Credit notes automatically sync with your tax provider (Quaderno, TaxJar, etc.) to maintain accurate tax records and compliance reports. ### Subscription Cancellation Protection When issuing a credit note with subscription cancellation, RevKeen implements a safety guard: if you select "Refund to Payment Method" with subscription cancellation, the subscription will **only cancel if the refund succeeds**. This prevents scenarios where a customer loses access but didn't receive their refund due to gateway errors or expired payment methods. If the refund fails, a warning is logged and the subscription remains active. You can then manually process the refund and cancel separately. ### Notifications When a credit note is issued, the following notifications are sent automatically: - **Merchant notification** -- An in-app notification appears in the dashboard bell icon confirming the credit note was issued, including the amount and customer name. - **Customer notification** -- An event is dispatched to the notifications service, which can deliver via email, SMS, or WhatsApp depending on your notification channel configuration in **Settings > Notifications**. > **Note:** Credit note email receipts and delivery channel selection (email, SMS, WhatsApp) per credit note are on the roadmap. Currently, customer notifications follow your global notification preferences. ### Creating Credit Notes via API ```typescript // Issue credit note with automatic refund (gateway auto-routed) const creditNote = await client.creditNotes.create({ invoiceId: 'inv_xxxxxxxx', amount: 5000, // $50.00 in cents reason: 'Service not delivered', creditMethod: 'refund_to_payment_method', cancelSubscription: true, }); // Issue credit note with customer balance const creditNote = await client.creditNotes.create({ invoiceId: 'inv_xxxxxxxx', amount: 5000, reason: 'Goodwill credit', creditMethod: 'customer_balance', }); // Credit note only (no financial movement) const creditNote = await client.creditNotes.create({ invoiceId: 'inv_xxxxxxxx', amount: 5000, reason: 'Manual adjustment', creditMethod: 'none', }); ``` #### V2 API: Auto-Routing When using the V2 API, pass `auto_route: true` to trigger multi-gateway reversal routing. For terminal (card-present) transactions, you can also specify `customer_present` to indicate whether the customer is physically at the terminal: ```typescript // V2 API with auto-routing const response = await fetch('/v2/credit_notes', { method: 'POST', headers: { 'Authorization': 'Bearer sk_live_xxxxxxxx', 'Content-Type': 'application/json', }, body: JSON.stringify({ invoice_id: 'inv_xxxxxxxx', amount_minor: 5000, credit_method: 'refund_to_payment_method', reason: 'Service not delivered', auto_route: true, // Enable multi-gateway routing customer_present: false, // Terminal: is customer at the device? }), }); ``` > **Audit Trail:** All credit notes include reason codes, creator information, timestamp, gateway operation details, and links to associated refunds/voids. They appear on customer statements and integrate with your accounting system for complete financial reconciliation. ## Payment Webhooks Listen for payment events to keep your systems in sync: | Event | Trigger | |-------|---------| | `payment.succeeded` | Payment completed successfully | | `payment.failed` | Payment was declined | | `payment.refunded` | Refund processed | | `payment.captured` | Authorized payment captured | | `payment.disputed` | Chargeback received | | `payment.requires_action` | Additional customer action needed | | `void.succeeded` | Pre-settlement void completed | | `void.failed` | Void failed (transaction already settled) | | `credit_note.created` | Credit note issued against invoice | | `credit_note.applied` | Credit note reversal completed (refund/void processed) | | `credit_note.voided` | Credit note canceled or voided | ## Best Practices - **Always Use Idempotency Keys** -- Include an idempotency key with payment requests to prevent duplicate charges on retries. - **Handle Webhooks** -- Don't rely solely on API responses. Use webhooks for reliable payment status updates. - **Store Transaction IDs** -- Always store the transaction ID from successful payments for refunds and support inquiries. - **Graceful Error Handling** -- Show user-friendly error messages and provide clear next steps when payments fail. - **Descriptive Statement Descriptors** -- Use descriptive statement descriptors so customers recognize charges on their bank statements and reduce chargebacks. ## Related - [Terminal Payments](/docs/using-revkeen/terminal) -- Accept card-present payments at a PAX terminal - [Dunning](/docs/using-revkeen/dunning) -- Automatic failed payment recovery - [Disputes](/docs/using-revkeen/disputes) -- Handle chargebacks and disputes - [Subscriptions](/docs/using-revkeen/subscriptions) -- Recurring billing guide --- # Products and Pricing Source: https://docs.revkeen.com/docs/using-revkeen/products-and-pricing Define products, configure pricing models, and create discount codes Products define what you sell and how you price it. RevKeen supports one-time purchases, recurring subscriptions, and usage-based billing. This page covers products, prices, and discounts. ## What is a Product? A Product represents something you sell. Products don't have prices directly attached to them. Instead, you create one or more **Prices** for each product, which allows you to offer: - Multiple pricing tiers (e.g., Basic, Pro, Enterprise) - Different billing intervals (monthly vs. annual) - Various currencies for international customers - One-time and recurring options for the same product ## Product Types | Kind | Description | Use Case | |------|-------------|----------| | `one_time` | Single purchase | Setup fees, one-off services | | `subscription` | Recurring billing | Monthly plans, memberships | | `service` | Service or package | Treatment packages, service bundles | ## Product Fields | Field | Type | Description | |-------|------|-------------| | `name` | string | Display name shown to customers | | `description` | string | Detailed product description | | `fulfillment_type` | enum | physical, digital, or none (service) | | `is_active` | boolean | Whether product is available for sale | | `media` | array | Product images and media files | | `metadata` | object | Custom key-value data for your use | ## Fulfillment Types The fulfillment type determines how the product is delivered to customers: | Type | Use Case | Examples | |------|----------|---------| | `physical` | Shipped items requiring delivery | Books, merchandise, equipment, hardware | | `digital` | Downloads or digital access | Software, e-books, courses, digital files | | `none` | Services with no delivery | Consulting, subscriptions, memberships | ## Creating Products ### Via Dashboard 1. Navigate to **Product > Catalogue** 2. Click **+ New Product** 3. Fill in product details (name, description, fulfillment type) 4. Add product images (optional) 5. Add benefits/features (optional) 6. Save the product 7. Add one or more prices to the product ### Via API #### Recurring Product (Subscription) ```typescript const product = await client.products.create({ productId: 'pro_monthly', name: 'Pro Plan', description: 'Full access to all features', kind: 'subscription', pricingModel: 'recurring', amountMinor: 2900, // $29.00 currency: 'USD', interval: 'month', intervalCount: 1, trialDays: 14, // Optional: Features list for checkout display features: [ 'Unlimited projects', 'Priority support', 'Advanced analytics', ], }); ``` #### One-Time Product ```typescript const product = await client.products.create({ productId: 'setup_fee', name: 'Setup Fee', description: 'One-time onboarding and configuration', kind: 'one_time', pricingModel: 'fixed', amountMinor: 9900, // $99.00 currency: 'USD', }); ``` ### Listing Products ```typescript // List all active products const products = await client.products.list({ isActive: true, }); // Filter by kind const subscriptions = await client.products.list({ kind: 'subscription', isActive: true, }); ``` ### Updating Products ```typescript const product = await client.products.update('prod_xxxxxxxx', { name: 'Pro Plan (2024)', amountMinor: 3900, // Price increase }); ``` > Updating a product's price doesn't affect existing subscriptions. New subscriptions will use the updated price. ### Archiving Products ```typescript // Archive a product (hide from new purchases) const product = await client.products.update('prod_xxxxxxxx', { isActive: false, }); ``` ## Product Benefits Benefits describe what's included with a product. They appear on checkout pages to help customers understand the value of what they're purchasing. > Benefits are displayed as a feature list on checkout pages. Add 3-5 key benefits to highlight the most important features. Example benefits: - Unlimited users - 24/7 email support - Advanced analytics dashboard - Custom integrations - Priority feature requests ## Product Best Practices 1. **Use clear, descriptive names** -- Names should be instantly recognizable to customers (e.g., "Pro Plan" not "SKU-12345"). 2. **Write compelling descriptions** -- Explain the value proposition, not just technical specs. 3. **Offer multiple price options** -- Monthly AND annual pricing can increase conversions by 20-30%. 4. **Add quality images** -- Use high-resolution product photos or illustrations. 5. **Highlight key benefits** -- List 3-5 benefits that matter most to your customers. --- ## Prices Prices define how much a product costs and how it's billed. A single product can have multiple prices, enabling flexible pricing strategies like offering both monthly and annual billing options. ### Price Types **One-Time Price** -- A single payment for a product. Perfect for physical goods, digital downloads, or services with a fixed scope. Example: Software license for $299. **Recurring Price** -- Repeated billing at a specified interval. Used for subscriptions, memberships, and ongoing services. Billing intervals: Daily, Weekly, Monthly, Yearly, or custom intervals (e.g., every 3 months, every 6 weeks). **Pay-What-You-Want** -- Let customers choose their own price. You can set minimum and suggested amounts. Great for donations, tips, or flexible pricing experiments. Example: Minimum $5, suggested $25. **Usage-Based (Metered)** -- Charge based on actual consumption. Track usage with meters and bill at the end of each billing period. Supports per-unit, graduated tiers, volume tiers, and package pricing. Metered products don't charge upfront -- they accumulate usage throughout the billing period and add the calculated charge to the invoice at renewal. See the full [Usage-Based Billing](/docs/using-revkeen/usage-based-billing) guide for setup. ### Price Fields | Field | Type | Description | |-------|------|-------------| | `amount_minor` | integer | Price in minor units (cents). $29.99 = 2999 | | `currency` | string | ISO currency code (USD, EUR, GBP, etc.) | | `type` | enum | one_time, recurring, or pay_what_you_want | | `billing_interval` | enum | day, week, month, year (recurring only) | | `billing_interval_count` | integer | Number of intervals between charges (default: 1) | | `trial_period_days` | integer | Free trial duration in days (recurring only) | | `is_active` | boolean | Whether price is available for new purchases | ### Creating Prices #### One-Time Price ```typescript const price = await client.prices.create({ productId: 'prod_xxxxxxxx', amountMinor: 29900, // $299.00 currency: 'USD', type: 'one_time', }); console.log(price.data.id); // price_xxxxxxxx ``` #### Monthly Subscription ```typescript const monthlyPrice = await client.prices.create({ productId: 'prod_xxxxxxxx', amountMinor: 2900, // $29.00/month currency: 'USD', type: 'recurring', billingInterval: 'month', billingIntervalCount: 1, trialPeriodDays: 14, // 14-day free trial }); ``` #### Annual Subscription (with discount) ```typescript // Annual price with 2 months free (10 months = $290 instead of $348) const annualPrice = await client.prices.create({ productId: 'prod_xxxxxxxx', amountMinor: 29000, // $290.00/year currency: 'USD', type: 'recurring', billingInterval: 'year', billingIntervalCount: 1, }); ``` #### Quarterly Billing (Custom Interval) ```typescript // Bill every 3 months const quarterlyPrice = await client.prices.create({ productId: 'prod_xxxxxxxx', amountMinor: 7500, // $75.00 every 3 months currency: 'USD', type: 'recurring', billingInterval: 'month', billingIntervalCount: 3, // Every 3 months }); ``` ### Trial Periods For recurring prices, you can offer a free trial period. During the trial: - Customer gets full access to the product - No payment is collected - Subscription status is `trialing` - At trial end, the first invoice is generated and charged > Trial periods are set on the Price, not the Product. This means you can offer different trial lengths for different pricing tiers. ### Multiple Prices per Product A single product can have multiple prices. Common patterns include: | Pattern | Example | Benefit | |---------|---------|---------| | Monthly + Annual | $29/mo or $290/yr | Capture both preference types | | Multiple tiers | Basic $19, Pro $49, Enterprise $199 | Different feature levels | | Multi-currency | $29 USD, 27 EUR, 24 GBP | Localized pricing | | One-time + Recurring | $99 setup + $29/mo | Setup fee with subscription | ### Pricing Best Practices 1. **Always offer annual pricing** -- Annual plans with a discount (typically 15-20% off) improve cash flow and reduce churn. 2. **Use trial periods strategically** -- 7-14 day trials work best for most SaaS products. 3. **Price in minor units** -- Always use cents/minor units to avoid floating point issues ($29.99 = 2999). 4. **Archive, don't delete** -- Set `is_active: false` instead of deleting prices to preserve history. ### Billing Intervals | Interval | intervalCount | Description | |----------|--------------|-------------| | `day` | 1 | Daily billing | | `week` | 1 | Weekly billing | | `week` | 2 | Bi-weekly billing | | `month` | 1 | Monthly billing | | `month` | 3 | Quarterly billing | | `year` | 1 | Annual billing | --- ## Discounts Discounts let you offer promotional pricing to customers. Create discount codes that customers can apply at checkout, or apply discounts directly to orders and subscriptions. ### Discount Types **Percentage Off** -- Reduce the total by a percentage (e.g., 20% off). Example: $100 with 20% off = $80. **Fixed Amount** -- Reduce the total by a specific amount (e.g., $25 off). Example: $100 with $25 off = $75. **Free Trial** -- Extend the trial period for subscriptions (e.g., 30-day trial instead of 14). Example: Add 30 days free trial period. ### Discount Fields | Field | Type | Description | |-------|------|-------------| | `code` | string | Discount code customers enter (e.g., SUMMER20) | | `type` | enum | percentage, fixed, or free_trial | | `amount_off` | integer | Fixed amount in minor units (for fixed type) | | `percent_off` | number | Percentage discount (for percentage type) | | `trial_days` | integer | Trial period in days (for free_trial type) | | `max_redemptions` | integer | Maximum number of times discount can be used | | `expires_at` | datetime | When the discount code expires | | `is_active` | boolean | Whether discount is currently usable | ### Discount Scope Control what the discount applies to: | Scope | Description | |-------|-------------| | `entire_order` | Applies to the total order/subscription amount | | `specific_products` | Only applies to selected products | | `subscription_only` | Only valid for recurring purchases | | `one_time_only` | Only valid for one-time purchases | ### Creating Discounts #### Via Dashboard 1. Navigate to **Product > Discounts** 2. Click **+ New Discount** 3. Enter discount code (e.g., SUMMER20) 4. Select discount type and amount 5. Configure scope and limits 6. Save the discount #### Via API ```typescript // Percentage discount const discount = await client.discounts.create({ code: 'SUMMER20', type: 'percentage', percentOff: 20, // Optional limits maxRedemptions: 100, expiresAt: '2026-08-31T23:59:59Z', // Optional: Limit to specific products productIds: ['prod_xxx', 'prod_yyy'], }); // Fixed amount discount const fixedDiscount = await client.discounts.create({ code: 'SAVE25', type: 'fixed', amountOff: 2500, // $25.00 currency: 'USD', }); // Free trial extension const trialDiscount = await client.discounts.create({ code: 'FREETRIAL30', type: 'free_trial', trialDays: 30, }); ``` ### Using Discounts at Checkout For checkout links, enable discount codes in the link settings: 1. Edit the checkout link 2. Enable **Allow discount codes** 3. Customers will see a discount code input field 4. Valid codes are applied automatically ### Using Discounts via API ```typescript // Apply discount to a subscription const subscription = await client.subscriptions.create({ customerId: 'cus_xxx', items: [{ priceId: 'price_xxx' }], discountId: 'disc_xxx', // Apply the discount }); // Apply discount to an order const order = await client.orders.create({ customerId: 'cus_xxx', lineItems: [{ priceId: 'price_xxx', quantity: 1 }], discountId: 'disc_xxx', }); ``` ### Tracking Redemptions Track how discounts are being used: - **Redemption count** -- How many times the code has been used - **Total discounted** -- Sum of all discount amounts applied - **Revenue impact** -- How much revenue was affected View discount analytics in **Product > Discounts** by clicking on any discount. ### Discount Best Practices 1. **Use memorable codes** -- SUMMER20, WELCOME10, BLACKFRIDAY are easy to remember and type. 2. **Set expiration dates** -- Create urgency and prevent indefinite discount usage. 3. **Limit redemptions** -- Control promotion costs by capping total uses. 4. **Track performance** -- Monitor redemption rates and revenue impact. 5. **Deactivate, don't delete** -- Set `is_active: false` to preserve history. ## Related - [Subscriptions](/docs/using-revkeen/subscriptions) -- Create subscriptions with products - [Usage-Based Billing](/docs/using-revkeen/usage-based-billing) -- Meter-based pricing for variable usage - [Checkout](/docs/using-revkeen/checkout) -- Sell products via checkout --- # Subscriptions Source: https://docs.revkeen.com/docs/using-revkeen/subscriptions Manage recurring billing with trials, discounts, and lifecycle events Subscriptions automate recurring billing by charging customers at regular intervals. RevKeen handles billing dates, invoicing, payment collection, and dunning automatically. This page covers the complete subscription lifecycle. ## Subscription Lifecycle ``` ┌─────────┐ ┌──────────┐ ┌────────┐ │ PENDING │────>│ TRIALING │────>│ ACTIVE │ └─────────┘ └──────────┘ └───┬────┘ │ ┌────────────────┼────────────────┐ │ │ │ v v v ┌──────────┐ ┌──────────┐ ┌──────────┐ │ PAST_DUE │ │ PAUSED │ │ CANCELED │ └────┬─────┘ └──────────┘ └──────────┘ │ v ┌──────────┐ │ UNPAID │ └────┬─────┘ │ v ┌──────────┐ │ EXPIRED │ └──────────┘ ``` ## Subscription Statuses | Status | Description | Billing | |--------|-------------|---------| | `pending` | Subscription created, awaiting first payment | Not billing | | `trialing` | In free trial period | Not billing | | `active` | Active and billing normally | Billing | | `past_due` | Payment failed, retrying | Attempting | | `paused` | Temporarily paused by customer or merchant | Not billing | | `canceled` | Subscription ended | Not billing | | `unpaid` | All payment retries exhausted | Stopped | | `expired` | Subscription term ended without renewal | Stopped | ## Creating Subscriptions ### Via Checkout The most common way to create subscriptions is through checkout links: 1. Create a checkout link with a recurring price 2. Customer completes checkout 3. Subscription is automatically created 4. First invoice is generated and charged ### Via API ```typescript const subscription = await client.subscriptions.create({ customerId: 'cus_xxxxxxxx', productId: 'prod_monthly', // Optional: Start with a trial trialDays: 14, // Optional: Apply a discount discountId: 'disc_xxxxxxxx', // Optional: Custom billing anchor (day of month) billingCycleAnchor: 1, // Bill on the 1st }); console.log(subscription.data.status); // 'trialing' or 'active' ``` ```python subscription = client.subscriptions.create( customer_id="cus_xxxxxxxx", product_id="prod_monthly", trial_days=14, discount_id="disc_xxxxxxxx", billing_cycle_anchor=1 ) print(subscription.data.status) # 'trialing' or 'active' ``` > If the product has a trial period defined, it will be applied automatically unless you explicitly set `trialDays: 0`. The billing interval (e.g., "Billed monthly") is automatically shown on all invoices, receipts, and the checkout success page. ## Subscription Items A subscription can contain multiple items, similar to Stripe's model. This allows you to bundle multiple products in a single subscription. ```typescript // Subscription with multiple items const subscription = await client.subscriptions.create({ customerId: 'cus_xxxxxxxx', items: [ { priceId: 'price_pro_monthly', // Pro plan at $49/mo quantity: 1, }, { priceId: 'price_extra_users', // Extra users at $10/mo each quantity: 5, }, ], }); // Each item generates its own line on invoices ``` ## Trial Periods Trials allow customers to try your product before paying: - Subscription status is `trialing` - Customer has full access during the trial - No payment is collected - At trial end, first invoice is created and charged - If payment fails, subscription enters `past_due` > Trial periods can be set on the Price or overridden when creating the subscription. ## Billing Cycle Each subscription has a billing cycle that determines when invoices are generated: | Field | Description | |-------|-------------| | `interval` | Billing frequency: `day`, `week`, `month`, `quarter`, `half_year`, `year` | | `interval_count` | Number of intervals between charges (e.g., 2 with month = every 2 months) | | `current_period_start` | Start of current billing period | | `current_period_end` | End of current billing period | | `billing_cycle_anchor` | Day of month/year for billing (e.g., 1st of each month) | > The billing interval is automatically shown on invoices, receipts, and the checkout success page so customers always know when their next charge will occur. ## Changing Plans ```typescript // Upgrade or downgrade immediately const subscription = await client.subscriptions.update('sub_xxxxxxxx', { productId: 'prod_enterprise', proration: 'create_prorations', // Prorate the difference }); // Proration options: // - 'create_prorations': Credit for unused time, charge for new plan // - 'none': No proration, new price starts next billing cycle // - 'always_invoice': Create and finalize proration invoice immediately ``` ## Proration Preview Preview proration calculations before changing plans to show customers what they will be charged. ```typescript // Get proration preview (newPlanId must be a UUID) const preview = await client.subscriptions.prorationPreview('sub_xxxxxxxx', { newPlanId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', }); console.log({ credit: preview.data.creditAmountMinor / 100, // Credit for unused time debit: preview.data.debitAmountMinor / 100, // Charge for new plan net: preview.data.netAmountMinor / 100, // Net charge/credit daysRemaining: preview.data.daysRemaining, }); ``` ## Cancelling Subscriptions ```typescript // Cancel at end of billing period (recommended) await client.subscriptions.cancel('sub_xxxxxxxx', { cancelAtPeriodEnd: true, }); // Cancel immediately (stop access now) await client.subscriptions.cancel('sub_xxxxxxxx', { cancelAtPeriodEnd: false, }); ``` > **Warning:** Immediate cancellation stops access right away. Use `cancelAtPeriodEnd: true` to let customers use their remaining time. ## Pausing Subscriptions ```typescript // Pause immediately await client.subscriptions.pause('sub_xxxxxxxx', { pauseAt: 'now', resumeAt: '2026-03-01T00:00:00Z', // Optional: Auto-resume date }); // Pause at end of current billing period (recommended) await client.subscriptions.pause('sub_xxxxxxxx', { pauseAt: 'period_end', }); // Resume manually await client.subscriptions.resume('sub_xxxxxxxx'); ``` > Using `pauseAt: 'period_end'` lets customers use their remaining paid time before pausing. ## Billing Anchor Day Set a specific day of the month for billing. The first invoice will be prorated to align with the anchor. ```typescript // Set billing anchor to the 15th of each month await client.subscriptions.setBillingAnchor('sub_xxxxxxxx', { day: 15, // 1-31 }); // For days 29-31, falls back to last day of short months ``` ## Smart Payment Retry RevKeen automatically retries failed payments using smart logic that distinguishes between temporary and permanent failures. | Failure Type | Examples | Retry Behavior | |-------------|----------|---------------| | **Soft Decline** | Insufficient funds, expired card | Retry on days 1, 3, 7 | | **Hard Decline** | Lost/stolen card, fraud | No retry, request new card | ## Order Creation on Renewal When a subscription renews and the invoice is paid, RevKeen checks whether the subscription contains products with a `fulfillment_type` of `physical` or `digital`. If so, an Order is automatically created to track fulfillment for that billing period. > This means a subscription for a monthly physical product (e.g., a supplement box) will create a new order every month when the renewal invoice is paid. Products with `fulfillment_type: none` (e.g., SaaS access) do not create orders. ## Dunning (Payment Recovery) When a subscription payment fails, RevKeen automatically enters the dunning process: 1. Subscription status changes to `past_due` 2. Payment is retried according to your retry schedule 3. Customer receives reminder emails 4. If all retries fail, subscription becomes `unpaid` or `canceled` > Configure dunning behavior at **Settings > Dunning** including retry intervals, email templates, and end behavior. See the [Dunning](/docs/using-revkeen/dunning) page for details. ## Subscription Events | Event | When Triggered | |-------|---------------| | `subscription.created` | Subscription is created | | `subscription.activated` | Trial ends or first payment succeeds | | `subscription.renewed` | Billing period renews successfully | | `subscription.updated` | Plan changed or details updated | | `subscription.paused` | Subscription is paused | | `subscription.resumed` | Paused subscription resumes | | `subscription.canceled` | Subscription is cancelled | | `subscription.expired` | Subscription term ended without renewal | | `subscription.past_due` | Payment failed, entering retry period | | `subscription.unpaid` | All payment retries exhausted | | `subscription.trial_will_end` | Trial period ending soon (3 days before) | ## Related - [Products and Pricing](/docs/using-revkeen/products-and-pricing) -- Define subscription products with pricing - [Invoices and Orders](/docs/using-revkeen/invoices-and-orders) -- How subscriptions generate invoices - [Dunning](/docs/using-revkeen/dunning) -- Configure payment recovery settings --- # Terminal Payments Overview Source: https://docs.revkeen.com/docs/using-revkeen/terminal Accept card-present payments through your PAX terminal with RevKeen Terminal Connector RevKeen Terminal lets you accept card-present payments at the point of sale using a PAX terminal connected through the RevKeen Terminal Connector. Payments flow through the same unified transaction ledger as your online payments, giving you a single view of all revenue. - How terminal payments work end-to-end - The three-component architecture - Supported devices and card entry modes - How terminal payments appear in your dashboard and reports ## How It Works RevKeen Terminal uses a three-component architecture to securely process card-present payments: ``` RevKeen Dashboard RevKeen Cloud Terminal Connector PAX Terminal │ │ │ │ │ "Charge £50.00" │ │ │ ├───────────────────────▶│ │ │ │ │ Send command (WS) │ │ │ ├────────────────────────▶│ │ │ │ │ Present card prompt │ │ │ ├───────────────────────▶│ │ │ │ │ Customer taps/ │ │ │ │ inserts card │ │ │ Approved ✓ │ │ │ │◀───────────────────────┤ │ │ Result │ │ │ │◀────────────────────────┤ │ │ Payment succeeded │ │ │ │◀───────────────────────┤ │ │ ``` 1. **You initiate a payment** from the RevKeen dashboard (or via the API). 2. **RevKeen Cloud sends the command** to your Terminal Connector over a secure WebSocket connection. 3. **The Connector forwards the command** to your PAX terminal on your local network. 4. **The customer presents their card** (tap, insert chip, or swipe). 5. **The terminal processes the payment** and returns the result through the same chain. 6. **RevKeen records the transaction** in your unified ledger with full card-present metadata. > **Note:** Card data never passes through RevKeen servers. The PAX terminal communicates directly with the payment processor. RevKeen only receives the transaction result (approval code, masked PAN, entry mode). ## Supported Devices RevKeen Terminal currently supports the **PAX A920 Pro** smart terminal. The A920 Pro features: - 5-inch touchscreen display - Contactless (NFC), chip (EMV), magnetic stripe, and manual entry - Built-in receipt printer - Wi-Fi and 4G connectivity - Android-based operating system with the PAX WebLink middleware > **Note:** Don't have a PAX terminal? You can request one directly from the terminal setup page in your [RevKeen Dashboard](https://app.revkeen.com/apps/marketplace/terminal). ## Card Entry Modes RevKeen Terminal supports all standard card entry methods. The entry mode is automatically recorded with each transaction: | Entry Mode | Description | Security | |------------|-------------|----------| | **Contactless (Tap)** | Customer taps their card or phone on the terminal | EMV cryptogram verified | | **EMV Chip** | Customer inserts their card into the chip reader | PIN or signature verified | | **Magnetic Stripe** | Customer swipes their card | Signature may be required | | **Manual Entry** | Card number entered manually on the terminal keypad | Used when card cannot be read | | **Fallback** | Terminal fell back from chip to swipe due to chip read failure | Logged for fraud monitoring | ## Terminal Payments in Your Dashboard ### Identifying Terminal Payments Terminal (card-present) payments are clearly distinguished from online (card-not-present) payments throughout the dashboard: | Field | Terminal Payment | Online Payment | |-------|-----------------|----------------| | **Payment Channel** | `card_present` | `card_not_present` | | **Entry Mode** | `contactless`, `emv_chip`, `magnetic_stripe`, etc. | Not applicable | | **Card Details** | Masked PAN, card scheme, entry mode | Card brand, last 4 digits | | **Terminal Info** | Device name, terminal serial number | Not applicable | ### Transaction History All terminal payments appear in your unified transaction list alongside online payments. You can filter by: - **Payment channel** -- Show only terminal payments or only online payments - **Device** -- Filter by specific terminal - **Entry mode** -- Filter by contactless, chip, or swipe - **Status** -- Approved, declined, refunded, voided ### Reporting Terminal payment data flows into all standard RevKeen reports: - **Revenue reports** include card-present and card-not-present breakdowns - **Payment method reports** show entry mode distribution (contactless vs chip vs swipe) - **Reconciliation** matches terminal transactions to your gateway settlement batches ## Getting Started To start accepting terminal payments, follow these steps: 1. **[Activate terminal payments](/docs/using-revkeen/terminal/activation)** -- Enable the terminal feature on your account 2. **[Install the connector](/docs/using-revkeen/terminal/connector-setup)** -- Download and set up the Terminal Connector app 3. **[Process your first payment](/docs/using-revkeen/terminal/processing-payments)** -- Send a payment to the terminal ## Frequently Asked Questions ### How long does a terminal payment take? Most contactless payments complete in under 5 seconds. Chip (EMV) payments typically take 10-15 seconds. The terminal has a 3-minute timeout window -- if no card is presented within 3 minutes, the payment is automatically cancelled. ### Can I use multiple terminals? Yes. You can pair multiple PAX terminals through one or more connectors. When initiating a payment, you select which terminal to send it to. ### What happens if my internet goes down during a payment? If the connector loses internet connectivity during a payment, the terminal may still process the card locally (depending on the terminal's offline mode). The result will sync to RevKeen when connectivity is restored. ### Are terminal payments PCI compliant? Yes. Card data is processed entirely on the PAX terminal and communicated directly to the payment processor. RevKeen never receives, stores, or transmits full card numbers. Only masked PANs and transaction metadata are stored. ## Related - [Processing Payments](/docs/using-revkeen/terminal/processing-payments) -- How to initiate sales at the terminal - [Refunds and Voids](/docs/using-revkeen/terminal/refunds-and-voids) -- Reverse terminal transactions - [Terminal API](/docs/developers/terminal-api/overview) -- Developer overview for programmatic terminal payments - [Payments and Refunds](/docs/using-revkeen/payments-and-refunds) -- Online payment processing and refund workflows --- # Activating Terminal Payments Source: https://docs.revkeen.com/docs/using-revkeen/terminal/activation Enable card-present payments on your RevKeen account Before you can accept card-present payments, you need to activate the terminal feature on your RevKeen account. - Prerequisites for terminal payments - How to activate terminal payments from the dashboard - What happens behind the scenes during activation - How to request hardware if you don't have a PAX terminal ## Prerequisites Before activating terminal payments, ensure you have: - An **active RevKeen account** with billing set up - A **payment gateway configured** (NMI is currently supported for card-present transactions) - A **PAX A920 Pro terminal** (or you can request one during setup) > **Note:** Terminal payments use the same gateway as your online payments. If you already have NMI configured for card-not-present transactions, you're ready to go. ## Activation Steps ### Step 1: Open the Terminal App 1. Log in to your [RevKeen Dashboard](https://app.revkeen.com) 2. Navigate to **Apps > Marketplace > Terminal** (or go directly to `/apps/marketplace/terminal`) 3. If you haven't activated terminal payments before, the activation wizard will display automatically ### Step 2: Complete the Activation Wizard The activation wizard walks you through: 1. **Equipment check** -- Confirm you have (or are requesting) a PAX terminal 2. **Install the connector** -- Download the RevKeen Terminal Connector for your operating system 3. **Link the connector** -- Generate a 6-digit linking code and enter it in the connector app > **Note:** The linking code expires in **10 minutes** and can only be used once. If it expires, you can generate a new one. ### Step 3: Verify Activation Once the connector is linked, you'll see it appear in the Terminal settings page with a status indicator: - **Online** (green dot) -- Connector is connected and ready - **Offline** (amber dot) -- Connector is not currently connected - **Not registered** -- Connector has not completed the linking process ## What Happens Behind the Scenes When you activate terminal payments, RevKeen: 1. Creates a **processing account** linked to your existing payment gateway 2. Registers the connector device in your merchant account 3. Establishes a secure WebSocket channel between the connector and RevKeen Cloud 4. Once a PAX terminal is paired, creates the device record with the terminal's serial number ## Requesting Hardware If you don't have a PAX terminal yet: 1. During the activation wizard (Step 1), click **Request Terminal** 2. RevKeen will create a hardware order on your behalf 3. You'll see a confirmation with a reference number 4. The terminal will be shipped to your registered business address You can continue with the connector installation while waiting for your terminal hardware to arrive. ## Next Steps - **[Install the Connector](/docs/using-revkeen/terminal/connector-setup)** -- Download and set up the Terminal Connector app - **[Process Your First Payment](/docs/using-revkeen/terminal/processing-payments)** -- Send a payment to the terminal --- # Installing the Connector Source: https://docs.revkeen.com/docs/using-revkeen/terminal/connector-setup Download, install, and link the RevKeen Terminal Connector to your account The RevKeen Terminal Connector is a desktop application that bridges your PAX terminal to RevKeen Cloud. It runs on your computer and communicates with the terminal over your local network. - How to download and install the connector for Windows and macOS - How to link the connector to your RevKeen account - How to pair a PAX terminal - How to set up multiple terminals - How auto-updates work ## System Requirements | Platform | Requirements | |----------|-------------| | **Windows** | Windows 10 or later, x64 processor | | **macOS (Apple Silicon)** | macOS 12 Monterey or later, M1/M2/M3/M4 chip | | **macOS (Intel)** | macOS 12 Monterey or later, Intel processor | The connector must be on the **same local network** (LAN) as your PAX terminal. ## Step 1: Download the Connector 1. Go to **Apps > Marketplace > Terminal** in your [RevKeen Dashboard](https://app.revkeen.com/apps/marketplace/terminal) 2. Click **Add Connector** to open the setup wizard 3. Select your operating system and click **Download** The dashboard auto-detects your platform and recommends the correct download. > **Note:** Downloads are served from `releases.revkeen.com`. The latest version is always available at the manifest URL: `https://releases.revkeen.com/terminal-connector/latest.json` ### Installation by Platform **Windows:** 1. Open the downloaded `.exe` installer 2. Follow the setup prompts and click Install 3. Launch RevKeen Terminal Connector from the Start menu **macOS:** 1. Extract the downloaded archive 2. Drag the app into your Applications folder 3. Open RevKeen Terminal Connector from Applications > **Note:** On macOS, you may see a security prompt the first time you open the app. Go to **System Settings > Privacy & Security** and click **Open Anyway**. ## Step 2: Link the Connector The connector needs to be linked to your RevKeen account with a one-time code. 1. In the dashboard setup wizard, click **Generate Code** 2. A **6-digit linking code** will appear on screen 3. In the Terminal Connector app, enter this code when prompted 4. The connector will register with your RevKeen account The code expires in **10 minutes** and can only be used once. If it expires, generate a new code from the dashboard. Once linked, the connector will show as **Online** in your dashboard. It maintains a persistent connection to RevKeen Cloud and reconnects automatically if the connection drops. ## Step 3: Pair Your PAX Terminal Once the connector is linked, it needs to discover and pair with your PAX terminal. ### Before Pairing Ensure your PAX terminal is ready: 1. **Power on** the PAX A920 terminal 2. **Connect to Wi-Fi** -- On the terminal, tap the three dots menu and go to Wi-Fi Settings. Connect to the same network as the computer running the connector. 3. **Open WebLink** -- Launch the WebLink app on the terminal. It should display "LISTENING (READY)". ### Pairing Process 1. The connector will automatically scan your local network for PAX terminals 2. If the terminal is found, it will appear in the connector's device list 3. If automatic discovery doesn't find the terminal, you can enter the terminal's IP address manually (find it in the terminal's network settings) 4. The connector verifies communication with the terminal and confirms pairing Once paired, the terminal appears in your dashboard with a green "Online" status. ## Multi-Terminal Setup You can connect multiple terminals through one or more connectors: - **One connector, multiple terminals** -- A single connector can pair with multiple PAX terminals on the same network - **Multiple connectors** -- Install the connector on different computers (e.g., at different locations) and link each one to the same RevKeen account When initiating a payment, you select which terminal to send it to. Each terminal is identified by its serial number and any custom name you've assigned. To add another connector: 1. Go to **Apps > Marketplace > Terminal** in the dashboard 2. Click **Add Connector** 3. Repeat the download, install, and linking process ## Auto-Updates The Terminal Connector checks for updates automatically. When a new version is available: - The dashboard shows an **"Update available"** banner with the new version number - You can click **Update** next to each outdated connector to push the update - The connector downloads and installs the update, then restarts automatically > **Note:** Updates cannot be pushed while a payment is in progress. Wait for any active payments to complete before updating. You can also trigger updates from the dashboard Terminal settings page by clicking the update button next to any outdated connector. ## Troubleshooting Connection Issues | Issue | Solution | |-------|----------| | Connector shows "Offline" | Ensure the connector app is running and your computer has internet access | | Terminal not found during pairing | Verify the terminal and computer are on the same Wi-Fi network. Check that WebLink is running and shows "LISTENING (READY)" | | Linking code expired | Generate a new code from the dashboard | | "Cannot reach terminal" error | Check firewall settings -- the connector needs to reach the terminal's IP on the local network | For more help, see the [Troubleshooting](/docs/using-revkeen/terminal/troubleshooting) page. ## Next Steps - **[Process Your First Payment](/docs/using-revkeen/terminal/processing-payments)** -- Send a payment to the terminal - **[Device Management](/docs/using-revkeen/terminal/device-management)** -- Monitor and manage your terminal fleet --- # Managing Devices Source: https://docs.revkeen.com/docs/using-revkeen/terminal/device-management Monitor and manage your terminal connectors and PAX devices Monitor your terminal fleet, check device health, update connectors, and manage pairings from the Terminal settings page. - How to view connected devices and their status - Health metrics and per-device statistics - How to force-update a connector - How to unpair a device ## Viewing Your Devices Navigate to **Apps > Marketplace > Terminal** in the [RevKeen Dashboard](https://app.revkeen.com/apps/marketplace/terminal) to see all your connectors and terminals. ### Device Status | Status | Meaning | |--------|---------| | **Online** (green dot) | Connector is connected, terminal is paired and reachable | | **Offline** (amber dot) | Connector has not sent a heartbeat in the last 5 minutes | | **Not registered** | Connector is created but the linking code has not been entered yet | A device must be **Online** with a paired terminal to accept payments. ### Terminal Cards Each paired terminal shows: - **Serial number** -- The PAX terminal's hardware serial number - **Connected connector** -- Which connector app is managing this terminal - **24-hour transaction count** -- Total payment attempts in the last 24 hours - **Approved count** -- Number of successful transactions Click **View Transactions** on any terminal card to filter the transaction history to that specific device. ## Health Metrics The Terminal settings page header shows aggregate health metrics across all your terminals: | Metric | Description | |--------|-------------| | **Transactions (24h)** | Total terminal payment attempts in the last 24 hours | | **Success rate** | Percentage of approved transactions | | **Average response time** | Mean time from payment request to terminal response | These metrics update every 30 seconds. ## Updating Connectors When a new version of the Terminal Connector is available, an amber banner appears at the top of the Terminal settings page: 1. The banner shows the new version number and which connectors are outdated 2. Click the **Update** button next to each connector you want to update 3. The update command is sent to the connector, which downloads and installs the update automatically > **Note:** You cannot update a connector while a payment is in progress. Wait for any active payments to complete first. ## Unpairing a Device To remove a connector and unpair its terminal: 1. Find the connector in the **Connectors** section 2. Click the delete (trash) icon 3. Confirm the deletion in the dialog This permanently removes the connector registration. The terminal will no longer accept payments through this connector. To reconnect, you'll need to go through the [linking process](/docs/using-revkeen/terminal/connector-setup) again with a new code. ## Adding More Connectors Click **Add Connector** in the Connectors section to start the setup wizard for an additional connector. This is useful when: - You have terminals at **multiple locations** (each location needs its own connector on a computer on that LAN) - You want a **backup connector** on a different computer at the same location ## Related - [Connector Setup](/docs/using-revkeen/terminal/connector-setup) -- Installing and linking the connector - [Troubleshooting](/docs/using-revkeen/terminal/troubleshooting) -- Common issues and solutions - [Terminal API Overview](/docs/developers/terminal-api/overview) -- API access patterns for terminal devices and payments --- # Processing Payments Source: https://docs.revkeen.com/docs/using-revkeen/terminal/processing-payments Initiate card-present payments from the dashboard or via the API Once your terminal is set up and online, you can start accepting card-present payments. Payments can be initiated from the RevKeen dashboard or programmatically via the API. - How to initiate a payment from an invoice - Walk-in payments without an invoice - Terminal selection with multiple devices - Payment progress and live status updates - Card entry modes and what they mean ## From the Dashboard ### Paying an Invoice 1. Navigate to the invoice you want to collect payment for 2. Click **Pay via Terminal** 3. If you have more than one terminal, select the device from the dropdown 4. The terminal will display the amount and prompt the customer to present their card 5. The customer taps, inserts, or swipes their card 6. Once approved, the invoice is automatically marked as paid A progress overlay shows real-time status updates as the payment moves through each stage: | Stage | What's Happening | |-------|-----------------| | **Sending to terminal** | The payment command is being sent to the device | | **Waiting for payment** | The terminal is displaying the amount and waiting for the card | | **Processing** | The terminal is communicating with the payment processor | | **Approved** | Payment succeeded -- the overlay auto-dismisses after 3 seconds | ### Walk-in Payments For ad-hoc or walk-in payments where no invoice exists: 1. Go to **Terminal > New Payment** in the dashboard 2. Enter the amount and currency 3. Select the target terminal 4. The payment is processed and recorded as a standalone transaction Walk-in payments are ideal for retail counters, pop-up events, or any scenario where you are collecting payment without a pre-created invoice. ## Terminal Selection When you have multiple terminals connected, you'll be prompted to choose which device to send the payment to. The selection shows: - **Device name** (e.g., "Front Desk Terminal") - **Terminal serial number** - **Status** (online/offline) > **Note:** Only terminals with an **Online** status can accept payments. If a terminal shows as offline, check that the connector is running and the terminal is powered on. ## Via the API You can initiate terminal payments programmatically using the Terminal Payments API: ```typescript const payment = await revkeen.terminalPayments.create({ device_id: 'd1e2f3a4-b5c6-7890-abcd-ef1234567890', amount_minor: 5000, // £50.00 currency: 'GBP', invoice_id: 'inv_xxxxxxxx', // Optional }); ``` The API returns immediately with a `requested` status. Use [webhooks](/docs/webhooks) to receive the result asynchronously. See the full [Terminal Payments API documentation](/docs/api-reference#tag/Terminal-Payments) for all endpoints and options. ## Payment Lifecycle Every terminal payment moves through a defined set of statuses: ``` requested → in_progress → approved / declined / error / timed_out → cancelled (if cancelled before completion) ``` | Status | Description | |--------|-------------| | `requested` | Payment command sent to terminal. Waiting for card presentation. | | `in_progress` | Terminal is processing the transaction. | | `approved` | Payment succeeded. Card was charged. | | `declined` | Card was declined by the issuer or processor. | | `cancelled` | Payment was cancelled before the customer presented their card. | | `error` | Terminal encountered an error (hardware failure, connection issue). | | `timed_out` | Terminal did not respond within 3 minutes. | ## Cancelling a Payment If a payment is still in the `requested` or `in_progress` state, you can cancel it: - **From the dashboard:** Click **Cancel** on the payment progress overlay - **Via the API:** `POST /v2/terminal-payments/{id}/cancel` Cancelling a payment that has already been approved has no effect -- use a [void or refund](/docs/using-revkeen/terminal/refunds-and-voids) instead. ## Handling Declines When a payment is declined, the progress overlay shows the decline reason with guidance: | Scenario | Guidance | |----------|---------| | **Insufficient funds** | Ask the customer to try a different card | | **Card expired** | Ask for a different card | | **Invalid PIN** | Ask the customer to re-enter their PIN | | **Card read error** | Ask to try again or use a different entry method | You can click **Try Again** to re-initiate the payment on the same terminal. ## Related - [Refunds and Voids](/docs/using-revkeen/terminal/refunds-and-voids) -- Reverse terminal transactions - [Terminal API Overview](/docs/developers/terminal-api/overview) -- Integration guidance for terminal devices and payments - [Troubleshooting](/docs/using-revkeen/terminal/troubleshooting) -- Common issues and solutions --- # Refunds & Voids Source: https://docs.revkeen.com/docs/using-revkeen/terminal/refunds-and-voids Reverse terminal transactions with refunds and voids Terminal refunds and voids work the same way as online payment reversals, but the reversal is processed through the physical terminal. RevKeen also supports issuing credit notes against terminal payments, which automatically routes to the correct reversal operation (terminal reversal, terminal refund, or gateway-direct fallback). - The difference between a void and a refund - How to process each from the dashboard - Partial refunds - When the customer needs to present their card again - How credit notes work with terminal payments ## Void vs Refund | | Void | Refund | |--|------|--------| | **When** | Before settlement (typically same business day) | After settlement | | **Effect** | Original charge is cancelled -- never appears on customer's statement | Separate credit transaction appears on customer's statement | | **Amount** | Always full amount | Full or partial | | **Card needed** | No -- processed without the card | May be required depending on terminal configuration | | **Speed** | Instant -- charge disappears | 3-10 business days for the credit to appear | > **Note:** RevKeen automatically determines whether a void or refund is appropriate based on the transaction's settlement status. The dashboard will show only the available options. ## Processing a Void If the original transaction has not yet settled (typically before the end of the business day): 1. Open the transaction in the dashboard 2. Click **Void** 3. The void command is sent to the terminal -- no card is needed 4. The original charge is cancelled and never appears on the customer's statement The progress overlay will show the void status in real time, similar to a payment. ## Processing a Refund For transactions that have already settled: 1. Open the transaction in the dashboard 2. Click **Refund** (full or partial amount) 3. The refund command is sent to the terminal 4. The customer may need to present their card again (depending on terminal configuration) 5. The refund appears as a separate transaction linked to the original sale ### Partial Refunds To refund only part of the original amount: 1. Open the transaction and click **Refund** 2. Enter the amount to refund (must be less than or equal to the original amount) 3. Optionally enter a reason for the refund 4. Confirm the refund You can issue multiple partial refunds against the same transaction, as long as the total refunded does not exceed the original amount. ## Card-Present Refunds Some payment processors require the customer's card to be present for a refund. If prompted: - Ask the customer to present the **same card** used for the original transaction - The terminal will process the refund and display the result - The refund amount is credited back to the same card > **Note:** If the customer no longer has the original card, contact your payment processor about alternative refund methods. ## Credit Notes for Terminal Payments You can also reverse terminal payments by issuing a credit note against the invoice. RevKeen automatically routes to the best reversal path: | Scenario | Reversal Path | Card Needed? | |----------|--------------|-------------| | Same-day, customer present | Terminal reversal (instant void on device) | No | | After settlement, customer present | Terminal refund (card re-present) | Yes | | Customer not present or terminal offline | Gateway-direct refund (no terminal) | No | When issuing a credit note from the dashboard, RevKeen checks whether the terminal is reachable and selects the optimal path. If the terminal is offline, the refund is processed through the payment processor automatically -- no manual intervention needed. See [Payments and Refunds](/docs/using-revkeen/payments-and-refunds#credit-notes) for the full credit note guide. ## Via the API Developers can process refunds and voids programmatically: ```typescript // Full refund await revkeen.terminalPayments.refund('tpa_xxxxxxxx'); // Partial refund await revkeen.terminalPayments.refund('tpa_xxxxxxxx', { amount_minor: 2500, // Refund £25.00 reason: 'Customer return', }); // Void await revkeen.terminalPayments.void('tpa_xxxxxxxx', { reason: 'Duplicate charge', }); ``` See the [Terminal Payments API](/docs/api-reference#tag/Terminal-Payments) for full documentation. ## Related - [Processing Payments](/docs/using-revkeen/terminal/processing-payments) -- Initiating terminal sales - [Payments and Refunds](/docs/using-revkeen/payments-and-refunds) -- Online payment refund workflows, credit notes - [Disputes](/docs/using-revkeen/disputes) -- Handle chargebacks on terminal transactions --- # Troubleshooting Source: https://docs.revkeen.com/docs/using-revkeen/terminal/troubleshooting Common terminal payment issues and how to resolve them This page covers common terminal payment issues and their solutions. - How to diagnose device offline issues - What to do when payments time out - Common decline codes and their meanings - Connector update problems - How to export logs for support ## Device Shows "Offline" The connector has not sent a heartbeat to RevKeen Cloud in the last 5 minutes. **Possible causes and solutions:** 1. **Connector app is not running** -- Check that the RevKeen Terminal Connector is running in your system tray (Windows) or menu bar (macOS). Restart it if needed. 2. **No internet connection** -- The connector needs internet access to maintain the connection to RevKeen Cloud. Verify your computer's internet connection. 3. **Firewall blocking WebSocket** -- The connector uses a WebSocket connection to `wss://ws.revkeen.com`. Ensure your network/firewall allows outbound WebSocket connections on port 443. 4. **Connector crashed** -- Restart the Terminal Connector application. > **Note:** If the connector shows as connected in the system tray but the dashboard shows offline, try restarting the connector. The WebSocket connection may have silently dropped. ## Payment Stuck on "Requested" The terminal did not respond within 3 minutes. The payment will automatically time out. **Common causes:** - **Terminal is powered off** or not connected to the network - **WebLink app is not running** on the terminal -- open it and ensure it shows "LISTENING (READY)" - **Connector can't reach the terminal** -- The connector and terminal must be on the same local network. Check that both are on the same Wi-Fi. - **Firewall between connector and terminal** -- Some corporate networks block device-to-device traffic on the LAN **Solution:** Check that the terminal is on and reachable, restart the connector if needed, and try the payment again. The stuck payment will automatically time out after 3 minutes. ## Payment Timed Out The 3-minute timeout elapsed without a response from the terminal. **What to check:** 1. Is the terminal powered on and showing the WebLink "LISTENING (READY)" screen? 2. Is the connector running and showing as Online in the dashboard? 3. Can the connector reach the terminal's IP on the local network? If the terminal was processing a card when the timeout occurred, the card may still have been charged. Check the terminal's receipt printer or on-screen result, and check your gateway's transaction log before retrying. ## Decline Codes Terminal declines use the same decline code system as online payments. Common terminal-specific scenarios: | Scenario | Cause | Action | |----------|-------|--------| | **Card Read Error** | Chip or contactless read failed | Ask customer to try again or use a different entry method | | **Insufficient Funds** | Card does not have enough balance | Ask for a different card | | **PIN Incorrect** | Wrong PIN entered | Customer can retry (usually 3 attempts) | | **Card Expired** | Card's expiry date has passed | Ask for a different card | | **Lost or Stolen Card** | Card reported to issuer | Do not attempt again -- ask for a different payment method | | **Call Issuer** | Bank requires voice authorisation | Customer should contact their bank | | **Invalid Card** | Card number not recognized | Try a different card | | **Restricted Card** | Card type not accepted for this transaction | Try a different card | The dashboard payment progress overlay shows the specific decline reason and recommended action for each scenario. ## Refund Requires Card Present Some payment processors require the customer's card to be present for a terminal refund. If the refund fails with this error: - Ask the customer to present the **same card** used for the original transaction - The terminal will process the refund and display the result If the customer no longer has the original card, contact your payment processor about processing a manual refund. ## Connector Update Issues ### Update Fails If a connector update fails to apply: 1. Ensure the connector has internet access 2. Check that no payment is in progress (updates are blocked during active payments) 3. Try clicking **Update** again from the dashboard 4. As a last resort, uninstall and reinstall the connector from the [releases page](https://releases.revkeen.com/terminal-connector/latest.json) ### Connector Won't Start After Update If the connector doesn't start after an update: 1. Check the system event log (Windows) or Console app (macOS) for error messages 2. Try reinstalling the connector from the dashboard 3. Contact support with the log file ## Exporting Logs for Support If you need to contact support, gather the following: 1. **Terminal serial number** -- Found in the Terminal settings page or on the terminal's label 2. **Connector version** -- Shown in the Terminal settings page next to each connector 3. **Transaction ID** -- If the issue is with a specific payment, note the terminal payment attempt ID 4. **Connector diagnostics** -- The connector can upload diagnostic logs to RevKeen for support analysis ## Frequently Asked Questions ### Can I use the terminal without internet? The connector requires internet to receive payment commands from RevKeen Cloud. However, the PAX terminal itself may support offline mode for certain transactions depending on your processor's configuration. Contact your payment processor for offline mode details. ### Why does the terminal show a different amount than expected? Verify the amount and currency in the payment request. Amounts are in minor units (pence/cents), so `5000` = £50.00. Check that the correct currency is selected. ### The terminal processed the payment but the dashboard still shows "Requested" This can happen if the connector lost internet after sending the command to the terminal but before receiving the result. The status will update when the connector reconnects, or when the 3-minute timeout triggers a status check. You can also check the terminal's receipt or your gateway dashboard to confirm the payment. ### Can I use the terminal with a different payment gateway? Terminal payments currently require NMI as the payment gateway. Support for additional gateways is planned. ## Related - [Terminal Overview](/docs/using-revkeen/terminal) -- How terminal payments work - [Device Management](/docs/using-revkeen/terminal/device-management) -- Monitor and manage your devices - [Terminal API Overview](/docs/developers/terminal-api/overview) -- Developer guidance for reliable terminal integrations --- # Usage-Based Billing Source: https://docs.revkeen.com/docs/using-revkeen/usage-based-billing Track consumption with meters, ingest usage events, and bill customers based on actual usage Usage-based billing (UBB) lets you charge customers based on what they actually use rather than a fixed price. RevKeen tracks consumption through meters, aggregates usage over billing periods, and automatically generates invoices with the correct charges. This page covers the complete UBB lifecycle from meter creation to invoice generation. ## What is Usage-Based Billing? Instead of charging a flat rate, usage-based billing measures actual consumption and bills accordingly. This model is common for API platforms, SaaS with variable workloads, and service businesses with per-session or per-unit pricing. | | Fixed Pricing | Usage-Based | Hybrid | |---|---|---|---| | **Revenue model** | Predictable flat rate | Pay-per-use | Base fee + overage | | **Best for** | Standard access plans | Variable consumption | Included allowance + extra | | **Example** | £50/month membership | £0.01 per API call | £50/mo + £5 per class over 10 | Real-world examples: API calls, compute hours, messages sent, storage GB, class bookings, patient appointments, transactions processed. ## How It Works ``` Create Meter → Attach Price → Add to Subscription → Ingest Events → Period Ends → Invoice Generated ``` 1. **Create a Meter** -- Define what you're tracking (e.g., "api_calls") and how to aggregate it (sum, count, max) 2. **Attach a Usage Price** -- Set the pricing model (per-unit, graduated tiers, volume, or package) 3. **Add to a Subscription** -- Wire the meter to a subscription as a metered item 4. **Ingest Events** -- Send usage events via API as consumption happens 5. **Period Ends** -- RevKeen aggregates all events for the billing period 6. **Invoice Generated** -- Usage charges appear as line items on the subscription invoice > **Note:** You can add metered usage to existing subscriptions -- no need to create new ones. Just add a metered subscription item alongside your existing fixed-price items. ## Meters ### What is a Meter? A meter is a named counter that tracks a specific type of usage. Each meter has an event name it listens for, an aggregation method, and optional filter conditions. When usage events arrive, RevKeen matches them to the appropriate meter and updates the running total. The chain is: **Meter → Events → Usage Records → Invoice Line Items**. ### Aggregation Types | Type | Description | Example | |------|-------------|---------| | `sum` | Sum of the `value_key` property across events | Total GB transferred | | `count` | Count of matching events | Number of API calls | | `count_unique` | Count of distinct values of the `unique_count_key` | Unique active users | | `max` | Maximum value of the `value_key` in the period | Peak concurrent connections | | `last` | Last reported value of the `value_key` | Current storage used | ### Creating Meters #### Via Dashboard Navigate to **Usage > Meters** in the sidebar Click **+ New Meter** Enter a name (e.g., "API Calls") and event name (e.g., `api_call`) Select the aggregation type (sum, count, count_unique, max, or last) For `sum`, `max`, or `last` -- specify the value key (the property in the event that holds the numeric value) Add filter conditions if needed (e.g., only count events where `environment = production`) Save the meter #### Via API ```typescript const meter = await revkeen.meters.create({ name: 'API Calls', event_name: 'api_call', aggregation: 'count', slug: 'api-calls', unit_name: 'calls', description: 'Tracks API calls per customer', }); ``` ```python meter = client.meters.create( name="API Calls", event_name="api_call", aggregation="count", slug="api-calls", unit_name="calls", description="Tracks API calls per customer", ) ``` ```bash curl -X POST "https://api.revkeen.com/v2/meters" \ -H "x-api-key: rk_live_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "name": "API Calls", "event_name": "api_call", "aggregation": "count", "slug": "api-calls", "unit_name": "calls" }' ``` ### Meter Fields | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Display name for the meter | | `event_name` | string | Yes | Event name to match incoming events against | | `aggregation` | enum | Yes | `sum`, `count`, `count_unique`, `max`, or `last` | | `slug` | string | No | URL-friendly identifier (unique per merchant) | | `value_key` | string | No | Property key for sum/max/last aggregations | | `unique_count_key` | string | No | Property key for count_unique aggregation | | `unit_name` | string | No | Display unit (e.g., "calls", "GB", "messages") | | `filter_conditions` | array | No | Conditions to filter which events are counted | | `carry_forward` | boolean | No | Whether to carry the last value into the next period | | `metadata` | object | No | Custom key-value data | > **Note:** The `event_name` and `aggregation` settings are immutable after creation. If you need to change these, create a new meter and archive the old one. ### Filter Conditions Filter conditions let you narrow which events a meter counts. For example, you can create a meter that only counts API calls in the `production` environment. Supported operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `contains`. ```typescript const meter = await revkeen.meters.create({ name: 'Production API Calls', event_name: 'api_call', aggregation: 'count', filter_conditions: [ { key: 'environment', operator: 'eq', value: 'production' }, ], }); ``` ## Pricing Models ### Per-Unit Pricing The simplest model: a fixed price multiplied by quantity. **Example:** £0.01 per API call. 15,000 calls = £150.00. ```typescript // Create a per-unit usage price const price = await revkeen.meters.createPrice(meter.id, { pricing_model: 'per_unit', unit_amount_minor: 1, // £0.01 currency: 'GBP', }); ``` ### Graduated Tiers Each tier applies only to the units within that range. Lower tiers are charged at their rate, higher tiers at theirs. **Example:** | Tier | Range | Unit Price | |------|-------|------------| | 1 | 1 – 1,000 | £0.10 | | 2 | 1,001 – 10,000 | £0.08 | | 3 | 10,001+ | £0.05 | **Calculation for 15,000 units:** - Tier 1: 1,000 × £0.10 = £100.00 - Tier 2: 9,000 × £0.08 = £720.00 - Tier 3: 5,000 × £0.05 = £250.00 - **Total: £1,070.00** ```typescript const price = await revkeen.meters.createPrice(meter.id, { pricing_model: 'graduated', currency: 'GBP', tiers: [ { first_unit: 1, last_unit: 1000, unit_amount_minor: 10 }, { first_unit: 1001, last_unit: 10000, unit_amount_minor: 8 }, { first_unit: 10001, last_unit: null, unit_amount_minor: 5 }, ], }); ``` ### Volume Tiers The total quantity determines a single price that applies to **all** units. Unlike graduated tiers, you don't mix rates. **Same tier table, different calculation for 15,000 units:** - Total lands in tier 3 → 15,000 × £0.05 = **£750.00** > **Note:** Graduated charges each tier separately. Volume picks one tier for everything. Graduated typically results in a higher total for the same usage. ```typescript const price = await revkeen.meters.createPrice(meter.id, { pricing_model: 'volume', currency: 'GBP', tiers: [ { first_unit: 1, last_unit: 1000, unit_amount_minor: 10 }, { first_unit: 1001, last_unit: 10000, unit_amount_minor: 8 }, { first_unit: 10001, last_unit: null, unit_amount_minor: 5 }, ], }); ``` ### Package Pricing Charge per block of units. Partial blocks are charged in full. **Example:** £5.00 per 100 API calls. - 250 calls = 3 packages × £5.00 = **£15.00** ```typescript const price = await revkeen.meters.createPrice(meter.id, { pricing_model: 'package', package_size: 100, unit_amount_minor: 500, // £5.00 per package currency: 'GBP', }); ``` ### Flat Fee + Usage (Base Charge) Add a minimum monthly charge on top of usage. The flat fee is charged regardless of consumption. **Example:** £20/month base + £0.05 per message. - 500 messages = £20.00 + (500 × £0.05) = **£45.00** ```typescript const price = await revkeen.meters.createPrice(meter.id, { pricing_model: 'per_unit', unit_amount_minor: 5, // £0.05 per message flat_fee_minor: 2000, // £20.00 base charge currency: 'GBP', }); ``` ## Connecting Meters to Subscriptions This is the critical bridge between tracking usage and billing for it. The wiring is: meter → usage price → subscription item. **Create a meter** that tracks the usage you want to bill for (e.g., API calls, class bookings) **Attach a usage price** to the meter with your chosen pricing model **Add the meter as a subscription item** on a product -- this links the meter to a customer's billing cycle **Ingest events** as consumption happens -- RevKeen aggregates usage automatically **At renewal**, RevKeen calculates the usage charge and adds it as a line item on the invoice alongside any fixed charges ```typescript // Create a subscription with both fixed and metered items const subscription = await client.subscriptions.create({ customerId: 'cus_xxxxxxxx', items: [ { priceId: 'price_fixed_monthly', // Fixed £50/month quantity: 1, }, { meterId: 'mtr_api_calls', // Metered usage priceId: 'price_per_unit', }, ], }); ``` > **Note:** Metered products don't charge upfront -- they accumulate usage throughout the billing period and add the calculated charge to the invoice at renewal. ## Hybrid Billing: Subscription + Usage The most common UBB pattern for service businesses. Combine a fixed subscription fee with metered overage charges. ### Complete Example: Fitness Studio A fitness studio charges £50/month membership that includes 10 classes. Additional classes cost £5 each. **Create the fixed product:** "Studio Membership" at £50/month **Create a meter:** `class_booking` with aggregation `count` **Create a graduated usage price** on the meter: | Tier | Range | Unit Price | |------|-------|------------| | 1 | 0 – 10 | £0.00 (included in membership) | | 2 | 11+ | £5.00 per class | **Create the subscription** with both items: ```typescript const subscription = await client.subscriptions.create({ customerId: 'cus_xxxxxxxx', items: [ { priceId: 'price_studio_membership' }, // £50/month fixed { meterId: 'mtr_class_booking', priceId: 'price_class_usage' }, // Usage-based ], }); ``` **Send events** when a class is booked: ```typescript await revkeen.usageEvents.ingest({ events: [{ name: 'class_booking', customer_id: 'cus_xxxxxxxx', quantity: 1, }], }); ``` **At billing period end**, invoice shows: | Line Item | Amount | |-----------|--------| | Studio Membership | £50.00 | | Class bookings (14 classes, 10 included) | £20.00 (4 × £5) | | **Total** | **£70.00** | > **Note:** The £0.00 first tier is key -- it represents the included allowance. Without it, every class would be charged from the first booking. ## Ingesting Usage Events ### Event Schema | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | Yes | Event name matching a meter's `event_name` | | `customer_id` | string | No | RevKeen customer ID | | `external_customer_id` | string | No | Your system's customer ID (alternative to `customer_id`) | | `subscription_id` | string | No | Associate with a specific subscription | | `meter_id` | string | No | Target a specific meter (if multiple meters share the same event name) | | `quantity` | number | No | Numeric value for the event (default: 1) | | `timestamp` | ISO 8601 | No | When the event occurred (default: now) | | `idempotency_key` | string | No | Unique key for safe retries | | `metadata` | object | No | Custom properties (filterable by meter filter conditions) | ### Sending Events ```typescript // Single event await revkeen.usageEvents.ingest({ events: [{ name: 'api_call', customer_id: 'cus_xxxxxxxx', quantity: 1, idempotency_key: 'evt_20260315_abc123', metadata: { endpoint: '/v2/users', region: 'eu-west-1' }, }], }); ``` ```python client.usage_events.ingest(events=[ { "name": "api_call", "customer_id": "cus_xxxxxxxx", "quantity": 1, "idempotency_key": "evt_20260315_abc123", "metadata": {"endpoint": "/v2/users", "region": "eu-west-1"}, } ]) ``` ```bash curl -X POST "https://api.revkeen.com/v2/usage-events" \ -H "x-api-key: rk_live_your_api_key" \ -H "Content-Type: application/json" \ -d '{ "events": [{ "name": "api_call", "customer_id": "cus_xxxxxxxx", "quantity": 1, "idempotency_key": "evt_20260315_abc123", "metadata": { "endpoint": "/v2/users", "region": "eu-west-1" } }] }' ``` ### Batch Ingestion Send up to 1,000 events in a single request: ```typescript await revkeen.usageEvents.ingest({ events: [ { name: 'api_call', customer_id: 'cus_aaa', quantity: 1 }, { name: 'api_call', customer_id: 'cus_bbb', quantity: 3 }, { name: 'storage_used', customer_id: 'cus_aaa', quantity: 1024 }, // ... up to 1,000 events ], }); ``` ### Dry Run Validate events without persisting them. Use this to test your event schema before production ingestion: ```typescript const result = await revkeen.usageEvents.dryRun({ events: [{ name: 'api_call', customer_id: 'cus_xxxxxxxx', quantity: 1, }], }); console.log(result.summary); // { would_ingest: 1, would_skip: 0, would_fail: 0 } ``` ### Idempotency Including an `idempotency_key` on events makes ingestion safe to retry. If you send the same key twice, the second request returns a `409 Conflict` and the event is not double-counted. ```typescript // Safe to retry on network failure await revkeen.usageEvents.ingest({ events: [{ name: 'api_call', customer_id: 'cus_xxxxxxxx', idempotency_key: `${customerId}_${Date.now()}`, }], }); ``` ### Late-Arriving Events When an event arrives after the billing period has been finalized, RevKeen automatically rolls it into the next billing period. The event is preserved with its original timestamp for auditability, but the charge appears on the next invoice. > **Note:** Events at the exact period boundary belong to the next period. Periods use half-open intervals: [start, end). ## Usage Records and Billing Periods ### How Usage Records Work RevKeen maintains one usage record per (meter, customer, billing period). As events arrive, the record's aggregated value is updated in real-time. At the end of the billing period, the record is finalized and locked for invoicing. ### Usage Record Statuses | Status | Description | |--------|-------------| | `pending` | Active billing period. Accumulating events. Value can still change. | | `finalized` | Billing period ended. Value is locked. Ready for invoicing. | | `invoiced` | Invoice has been generated with this usage record's charges. | | `voided` | Record was voided (e.g., subscription cancelled mid-period). | ### Viewing Current Usage #### Via Dashboard Navigate to **Usage > Meters**, click on a meter to see real-time aggregated usage per customer, daily usage charts, and recent events. #### Via API ```typescript // Get current usage balance for a customer const balance = await revkeen.usageBalance.get({ meter_id: 'mtr_xxxxxxxx', customer_id: 'cus_xxxxxxxx', }); console.log(`Current usage: ${balance.meters[0].current_value}`); console.log(`Estimated charge: £${balance.meters[0].estimated_amount_minor / 100}`); ``` ```typescript // Get aggregated usage over a time range const aggregate = await revkeen.usageEvents.aggregate('mtr_xxxxxxxx', { customer_id: 'cus_xxxxxxxx', start_date: '2026-03-01T00:00:00Z', end_date: '2026-03-31T23:59:59Z', }); ``` ### Billing Period Alignment Usage periods align with subscription billing cycles. If a customer's subscription renews on the 15th of each month, the usage period runs from the 15th to the 14th of the following month. ## Usage Invoices When a billing period ends, RevKeen generates an invoice that includes usage charges as line items. Each meter generates a separate line item showing: - Meter name - Billing period (start and end dates) - Total quantity consumed - Unit price or tier breakdown - Calculated charge For tiered pricing, the line item details include a breakdown of how many units fell into each tier and the charge for each. > **Note:** Usage invoices are generated automatically when the billing period ends. For hybrid subscriptions, usage charges appear alongside fixed charges on the same invoice. ## Dashboard Guide ### Meters List Navigate to **Usage > Meters** in the sidebar. The meters list shows all your meters with their event counts, status, and aggregation type. ### Meter Detail Click on any meter to see: - **Usage chart** -- Daily, weekly, or monthly aggregation of usage over time - **Customer breakdown** -- Usage per customer, sorted by consumption - **Recent events** -- Latest events matched to this meter - **Pricing configuration** -- Attached usage prices and tier configuration ### Usage Analytics The usage analytics dashboard shows: - Revenue by meter - Top customers by usage - Usage trends over time - Margin analysis (when `default_cost_per_unit_minor` is set on meters) ## Best Practices 1. **Always include idempotency keys** -- Safe to retry on network failure without double-counting events. 2. **Send events in real-time** -- Don't batch events to end-of-day. Real-time ingestion gives your customers accurate usage dashboards and prevents surprises at billing time. 3. **Use filter conditions for segmentation** -- Add properties like `region`, `environment`, or `plan_tier` to events, then create separate meters with filter conditions for granular billing and analytics. 4. **Start with per-unit pricing** -- The simplest model to reason about. Graduate to tiered pricing once you understand your customers' usage patterns. 5. **Use graduated tiers with a £0.00 first tier** -- This creates "included allowance" pricing (e.g., 100 free API calls, then £0.01 each after). 6. **Use the usage balance endpoint for customer dashboards** -- Build customer-facing usage displays with `GET /v2/usage-balance` so customers can monitor their consumption in real-time. 7. **Validate with dry runs first** -- Use `POST /v2/usage-events/dry-run` to verify your event schema matches your meters before sending production events. ## Related - [Products and Pricing](/docs/using-revkeen/products-and-pricing) -- Define products with usage-based prices - [Subscriptions](/docs/using-revkeen/subscriptions) -- Attach metered items to subscriptions - [Invoices and Orders](/docs/using-revkeen/invoices-and-orders) -- How usage charges appear on invoices - [Usage API Reference](/docs/api-reference#tag/Meters) -- Full REST reference for meters, usage events, and pricing --- # Wallets Source: https://docs.revkeen.com/docs/using-revkeen/wallets Give customers a stored-balance wallet for instant payments with zero processing fees Wallets let customers pay from a stored balance, eliminating card processing fees on every wallet transaction. Customers fund their wallet via card or bank transfer, and future payments draw instantly from the balance. ## What are Wallets? A wallet is a closed-loop stored-balance account attached to each customer. When a customer has wallet funds available, they can pay invoices instantly without a card transaction — meaning zero processing fees for you. Wallets support multiple balance types, expiry tracking via lots, and hold/capture mechanics for checkout atomicity. ## Balance Types Every wallet credit is tagged with a funding type that determines how the balance can be used: | Funding Type | Description | Withdrawable | |-------------|-------------|--------------| | **cash** | Customer-funded via card or bank transfer | Yes | | **promotional** | Merchant-issued promotional credit | No | | **code_redemption** | Credit from redeeming a wallet code | Depends on code type | | **refund** | Credit issued in lieu of a card refund | Yes | | **manual_adjustment** | Manual adjustment by merchant | Yes | ## How It Works The wallet payment flow follows a hold/capture pattern for atomicity: ``` Fund → Hold → Capture → Settle ``` 1. **Fund** — Customer tops up their wallet, or merchant credits the account 2. **Hold** — At checkout, the required amount is reserved (held) from the balance 3. **Capture** — Once the order is confirmed, the hold is captured as a debit 4. **Settle** — The transaction is recorded and the invoice marked as paid If the checkout is abandoned or fails, the hold is released and the balance is restored. ## Wallet Settings Configure wallet behavior for your account in **Settings > Billing**: | Setting | Description | |---------|-------------| | **Auto-apply at checkout** | Automatically apply wallet balance to invoices during checkout | | **Allow top-up** | Let customers add funds to their wallet | | **Low balance threshold** | Trigger a webhook when a customer's balance drops below this amount | | **Credit expiry days** | Default expiry period for wallet credits (lots) | | **Top-up amounts** | Preset top-up amounts shown to customers | ## Related - [Managing Balances](/docs/using-revkeen/wallets/managing-balances) — Credit, debit, and transaction history - [Wallet Codes](/docs/using-revkeen/wallets/wallet-codes) — Create and manage redeemable codes - [Checkout Integration](/docs/using-revkeen/wallets/checkout-integration) — How wallets work at checkout - [Customer Portal](/docs/using-revkeen/wallets/customer-portal) — Customer-facing wallet features - [Products and Pricing](/docs/using-revkeen/products-and-pricing) — Product configuration --- # Checkout Integration Source: https://docs.revkeen.com/docs/using-revkeen/wallets/checkout-integration How wallet balances work at checkout with hold/capture mechanics and partial payments Wallets integrate directly into the RevKeen checkout flow. Customers can pay partially or fully from their wallet balance, reducing or eliminating card processing fees. ## Auto-Apply Wallet Balance When **Auto-apply at checkout** is enabled in your wallet settings, the checkout page automatically applies the customer's available wallet balance to the invoice total. - If the wallet covers the full amount, no card payment is required - If the wallet covers part of the amount, the customer pays the remainder by card - Customers can opt out by unchecking "Use wallet balance" at checkout ## "Have a Code?" Input Every checkout page includes a code redemption field: 1. Customer enters a wallet code in the "Have a code?" input 2. The code is validated in real-time 3. On success, the credit is added to the customer's wallet 4. The newly added balance is applied to the invoice This works for both existing customers and guest checkout (code credit is applied as a direct invoice deduction for guests). ## Payment Scenarios ### Full Wallet Payment When the wallet balance covers the entire invoice: ``` Invoice total: £50.00 Wallet balance: £75.00 Card charge: £0.00 (no processing fees!) New wallet balance: £25.00 ``` ### Partial Payment (Wallet + Card) When the wallet balance covers part of the invoice: ``` Invoice total: £50.00 Wallet balance: £20.00 Wallet applied: £20.00 Card charge: £30.00 New wallet balance: £0.00 ``` ### No Wallet Balance Standard card payment flow. The wallet section is hidden if the customer has no balance. ## Hold/Capture/Release Pattern Wallet payments use a reservation pattern to ensure atomicity: ### Flow 1. **Hold** — When the customer clicks "Pay", a hold is created for the wallet portion 2. **Card charge** — If a card payment is needed for the remainder, it's processed 3. **Capture** — If everything succeeds, the wallet hold is captured (balance deducted) 4. **Release** — If the card charge fails, the wallet hold is released (balance restored) ### Why Holds? Without holds, a race condition could occur: - Customer A uses wallet balance at checkout - Card payment fails - Meanwhile, customer A's balance was already deducted - Now they've lost money with no purchase Holds prevent this by reserving but not deducting until the full payment is confirmed. ### Hold Expiry Holds expire automatically after 30 minutes. This prevents balance from being locked indefinitely if a checkout session is abandoned. ## Guest Checkout Code Redemption For guest checkout (no customer account): 1. Guest enters a wallet code at checkout 2. If the code is unrestricted (not tied to a specific customer), it's accepted 3. The code value is applied as a direct deduction on the invoice 4. No wallet account is created — the credit is consumed immediately ## API Flow (Developer Reference) For custom checkout integrations: ``` 1. GET /v2/wallet/customers/{customerId}/balance → Check available balance 2. POST /v2/wallet/customers/{customerId}/hold → Reserve wallet amount for checkout 3. Process card payment for remainder (if any) 4a. POST /v2/wallet/customers/{customerId}/hold/{holdId}/capture → Payment succeeded: capture the hold 4b. POST /v2/wallet/customers/{customerId}/hold/{holdId}/release → Payment failed: release the hold ``` ## Related - [Wallets Overview](/docs/using-revkeen/wallets) — What wallets are and how they work - [Managing Balances](/docs/using-revkeen/wallets/managing-balances) — Credit and debit operations - [Wallet Codes](/docs/using-revkeen/wallets/wallet-codes) — Redeemable credit codes - [Checkout](/docs/using-revkeen/checkout) — General checkout configuration --- # Customer Portal Source: https://docs.revkeen.com/docs/using-revkeen/wallets/customer-portal Customer-facing wallet features including balance display, transaction history, and code redemption The Customer Portal gives your customers self-service access to their wallet balance, transaction history, and code redemption. ## Balance Card When a customer logs into the portal, their wallet balance is displayed as a card: - **Available balance** — Current spendable balance - **Held balance** — Amount reserved by in-progress checkouts - **Currency** — Displayed in the merchant's configured currency The balance card is only shown if the customer has a non-zero balance or if wallets are enabled for the merchant. ## Transaction History Customers can view their full wallet transaction history: - **Credits** — Top-ups, code redemptions, refund credits - **Debits** — Checkout payments, manual adjustments - **Holds** — In-progress reservations (shown as pending) Each transaction shows the amount, type, description, and date. ## Redeem a Code Customers can redeem wallet codes directly from the portal: 1. Click **Redeem a Code** on the wallet balance card 2. Enter the code (e.g., `RK-AB12-CD34` or a custom code like `SUMMER2026`) 3. The code is validated: - Must be `active` status - Must not be expired - Must not be restricted to a different customer 4. On success, the credit is added to the wallet immediately 5. The balance card updates to reflect the new balance ### Error States | Error | Cause | |-------|-------| | "Invalid code" | Code doesn't exist or is restricted to another customer | | "Code expired" | Code has passed its expiry date | | "Code already redeemed" | Code has already been used | | "Code revoked" | Merchant has revoked the code | ## Portal URL Configuration The Customer Portal is accessible at your configured portal URL: ``` https://{your-checkout-domain}/portal ``` Customers receive a magic link via email to access the portal — no password required. ## Wallet Visibility The wallet section in the portal is conditionally shown: | Condition | Wallet Visible | |-----------|---------------| | Wallets enabled + customer has balance | Yes | | Wallets enabled + customer has no balance | Yes (with "Redeem a Code" prompt) | | Wallets disabled | No | ## Related - [Wallets Overview](/docs/using-revkeen/wallets) — What wallets are and how they work - [Wallet Codes](/docs/using-revkeen/wallets/wallet-codes) — Creating and managing codes - [Customer Portal](/docs/using-revkeen/customer-portal) — General portal configuration --- # Managing Balances Source: https://docs.revkeen.com/docs/using-revkeen/wallets/managing-balances Credit, debit, and manage customer wallet balances with transaction history and lot tracking Manage customer wallet balances through the dashboard or API. Every balance change is tracked as a transaction with full audit history. ## Credit Wallet (Add Funds) Add funds to a customer's wallet in three ways: ### From the Dashboard 1. Go to **Customers** and select a customer 2. Open the **Wallet** tab 3. Click **Credit Wallet** 4. Enter the amount, select the funding type, and add an optional description 5. Click **Confirm** ### Via Wallet Code Redemption Customers redeem wallet codes through the Customer Portal or at checkout. See [Wallet Codes](/docs/using-revkeen/wallets/wallet-codes) for details. ### Via the API ```bash POST /v2/wallet/customers/{customerId}/credit Content-Type: application/json { "amountCents": 5000, "currency": "GBP", "sourceType": "manual", "fundingType": "cash", "description": "Loyalty reward" } ``` Response: ```json { "transactionId": "wt_abc123", "balanceCents": 7500, "lotId": "wl_def456" } ``` ## Debit Wallet (Remove Funds) Debit funds manually or automatically at checkout. ### Manual Debit (Dashboard) 1. Open the customer's **Wallet** tab 2. Click **Debit Wallet** 3. Enter the amount and reason 4. Click **Confirm** ### Manual Debit (API) ```bash POST /v2/wallet/customers/{customerId}/debit Content-Type: application/json { "amountCents": 2000, "currency": "GBP", "sourceType": "manual", "description": "Correction" } ``` > Debits fail with a 422 error if the customer has insufficient balance. ## Transaction History Every wallet operation creates a transaction record. View the full history in the customer's **Wallet** tab or via the API. ### Transaction Fields | Field | Description | |-------|-------------| | **type** | `credit` or `debit` | | **amountCents** | Amount in minor units | | **sourceType** | Origin: `manual`, `checkout`, `code_redemption`, `refund`, `system` | | **fundingType** | Balance category: `cash`, `promotional`, `code_redemption`, `refund` | | **description** | Human-readable note | | **createdAt** | Timestamp | | **lotId** | Associated wallet lot (for credits) | ### Query via API ```bash GET /v2/wallet/customers/{customerId}/transactions?limit=50&offset=0&type=credit ``` ## Wallet Lots Credits are tracked as **lots** — individual balance entries with optional expiry dates. When a debit occurs, lots are consumed in FIFO order (oldest first). ### Lot Fields | Field | Description | |-------|-------------| | **id** | Unique lot identifier | | **originalAmountCents** | Amount when created | | **remainingAmountCents** | Current remaining balance | | **fundingType** | Balance category | | **expiresAt** | Optional expiry date (null = never expires) | | **status** | `active`, `depleted`, `expired` | Expired lots are automatically marked by a daily cron job. The remaining balance of expired lots is forfeited. ## Holds (Reservations) Holds reserve wallet balance during checkout to prevent double-spending. ### Hold Lifecycle 1. **Create hold** — Reserves amount from available balance 2. **Capture hold** — Converts hold to a debit (payment confirmed) 3. **Release hold** — Returns held amount to available balance (checkout abandoned) ### Create Hold (API) ```bash POST /v2/wallet/customers/{customerId}/hold { "amountCents": 3000, "currency": "GBP", "reference": "inv_abc123" } ``` ### Capture Hold ```bash POST /v2/wallet/customers/{customerId}/hold/{holdId}/capture ``` ### Release Hold ```bash POST /v2/wallet/customers/{customerId}/hold/{holdId}/release ``` > Holds expire automatically after 30 minutes if neither captured nor released. ## Related - [Wallets Overview](/docs/using-revkeen/wallets) — What wallets are and how they work - [Wallet Codes](/docs/using-revkeen/wallets/wallet-codes) — Redeemable credit codes - [Checkout Integration](/docs/using-revkeen/wallets/checkout-integration) — Wallet at checkout --- # Wallet Codes Source: https://docs.revkeen.com/docs/using-revkeen/wallets/wallet-codes Create and manage redeemable wallet codes for promotions, gifts, refunds, and referrals Wallet codes are redeemable codes that add credit to a customer's wallet. Use them for promotions, gift cards, referral rewards, refund credits, and goodwill gestures. ## What are Wallet Codes? A wallet code is a unique alphanumeric string that a customer redeems to receive wallet credit. Codes can be restricted to specific customers or available to anyone. ## Code Types | Type | Use Case | Example | |------|----------|---------| | **goodwill** | Service recovery, apology credit | "Sorry for the disruption" | | **promotional** | Marketing campaigns, seasonal offers | "Summer 2026 promo" | | **gift** | Gift cards, prepaid credit | "Birthday gift from John" | | **referral** | Referral program rewards | "Referred by customer X" | | **refund** | Refund issued as wallet credit | "Refund for INV-001" | ## Creating Codes ### From the Dashboard 1. Go to **Product > Wallet Codes** 2. Click **Create Code** 3. Configure: - **Amount** — Credit value in your currency - **Code type** — Select from the types above - **Code** — Auto-generated (`RK-XXXX-XXXX` format) or enter a custom code - **Customer restriction** — Any customer, or a specific customer - **Expiry date** — Optional; code becomes invalid after this date - **Description** — Internal note 4. Click **Create** ### Via the API ```bash POST /v2/wallet-codes { "amountCents": 2500, "currency": "GBP", "codeType": "promotional", "customCode": "SUMMER2026", "customerId": null, "expiresAt": "2026-09-01T00:00:00Z", "description": "Summer promotion" } ``` ## Code Format - **Auto-generated**: `RK-XXXX-XXXX` (uppercase alphanumeric, 8 characters after prefix) - **Custom**: Any string up to 50 characters (automatically uppercased, spaces removed) Custom codes are validated for uniqueness within the merchant's account. ## Customer Restrictions | Mode | Behavior | |------|----------| | **Any customer** | Any customer of the merchant can redeem the code | | **Specific customer** | Only the assigned customer can redeem | When a code is restricted to a specific customer, other customers see an "Invalid code" error. ## Expiry and Auto-Expiry - Set an optional expiry date when creating a code - A daily cron job marks expired codes as `expired` - Expired codes cannot be redeemed - Already-redeemed credits are not affected by code expiry (lot expiry is separate) ## Redemption Flow ### Customer Portal 1. Customer logs into the Customer Portal 2. Clicks **Redeem a Code** on their wallet balance card 3. Enters the code 4. Credit is added instantly to their wallet ### At Checkout 1. Customer sees "Have a code?" input on the checkout page 2. Enters the code 3. Credit is applied to the invoice total 4. Remaining balance (if any) stays in the wallet ### Via API ```bash POST /v2/wallet-codes/{codeId}/redeem { "customerId": "cust_abc123" } ``` ## Status Lifecycle ``` active → redeemed active → expired active → revoked ``` | Status | Description | |--------|-------------| | **active** | Code is available for redemption | | **redeemed** | Code has been redeemed by a customer | | **expired** | Code passed its expiry date | | **revoked** | Code was manually revoked by the merchant | ## Managing Codes ### View All Codes Go to **Product > Wallet Codes** to see all codes with status, amount, customer, and dates. ### Revoke a Code 1. Find the code in the list 2. Click the actions menu 3. Select **Revoke** Revoking a code does not remove credit already redeemed. ### Bulk Create Use the API to create multiple codes programmatically for campaigns: ```bash # Create 100 promotional codes for i in $(seq 1 100); do curl -X POST /v2/wallet-codes \ -d '{"amountCents": 1000, "codeType": "promotional"}' done ``` ## Related - [Wallets Overview](/docs/using-revkeen/wallets) — How wallets work - [Managing Balances](/docs/using-revkeen/wallets/managing-balances) — Credit and debit operations - [Customer Portal](/docs/using-revkeen/wallets/customer-portal) — Customer code redemption --- # Money Source: https://docs.revkeen.com/docs/money How money flows through RevKeen - from collection to payout RevKeen handles every stage of your payment lifecycle: collecting money from customers, processing it through your gateway, settling funds, and depositing them into your bank account. This section covers each stage in detail. ## How money moves through RevKeen The payment lifecycle follows four stages: 1. **Collection** -- A customer pays via checkout link, invoice, or subscription renewal. RevKeen sends the transaction to your payment gateway for authorization. 2. **Processing** -- The gateway authorizes the card, performs fraud checks, and returns a result. RevKeen records the transaction and updates the invoice status. 3. **Settlement** -- The gateway batches authorized transactions and submits them to the card networks. Funds move from the customer's bank to the gateway's settlement account. 4. **Payout** -- The gateway deposits settled funds (minus processing fees) into your bank account on your configured schedule. ## What you can track | Area | What it shows | Learn more | |------|---------------|------------| | **Analytics** | Revenue metrics, MRR, churn, checkout conversion rates | [Analytics](/docs/money/analytics) | | **Income** | Every transaction with amounts, fees, and net totals | [Income](/docs/money/income) | | **Payouts** | Bank deposits, settlement timing, and reconciliation | [Payouts](/docs/money/payouts) | | **Refunds** | Full and partial refunds, status tracking | [Refunds](/docs/money/refunds) | | **Disputes** | Chargebacks, evidence submission, win/loss outcomes | [Disputes](/docs/money/disputes) | | **Account and KYC** | Verification status, bank details, compliance documents | [Account and KYC](/docs/money/account-and-kyc) | | **Tax** | Automatic tax calculation with Quaderno integration | [Tax](/docs/money/tax) | | **Fees** | RevKeen pricing, transaction fees, what is included | [How Fees Work](/docs/money/how-fees-work) | ## Key concepts - **Gross revenue** is the total amount collected before any deductions. - **Net revenue** is what remains after processing fees, refunds, and chargebacks. - **MRR (Monthly Recurring Revenue)** tracks the predictable revenue from active subscriptions. - **Void vs refund**: If a transaction has not yet settled, RevKeen automatically performs a void instead of a refund. Voids release the authorization hold without moving funds and avoid processing fees. ## Where to start - If you are setting up for the first time, begin with [Account and KYC](/docs/money/account-and-kyc) to verify your business and connect your bank account. - To understand your revenue at a glance, go to [Analytics](/docs/money/analytics). - To review individual transactions, go to [Income](/docs/money/income). --- # Account and KYC Source: https://docs.revkeen.com/docs/money/account-and-kyc Manage your processing account, verification documents, and compliance status The Account and KYC section manages your identity verification, business documentation, and banking details required to receive payouts. ## Accessing Account Settings Navigate to **Finance > Account** to manage your account details. ## Verification Status | Status | Description | Capabilities | |--------|-------------|-------------| | `Pending` | Verification in progress | Limited processing | | `Verified` | Fully verified | Full capabilities | | `Action Required` | Additional info needed | May have restrictions | ## KYC Requirements Know Your Customer (KYC) verification typically requires documentation based on your business type. ### For Individuals / Sole Proprietors - Legal name - Date of birth - Address - Social Security Number (SSN) or Tax ID - Government-issued photo ID ### For Businesses - Legal business name - Business address - EIN or Tax ID - Business type (LLC, Corporation, etc.) - Formation documents (may be required) - Beneficial owner information > Verification requirements vary by country and business type. RevKeen will prompt you for exactly what is needed. ## Submitting Documents 1. Go to **Finance > Account** 2. Click **Complete Verification** 3. Follow the prompts to provide required information 4. Upload clear photos of requested documents 5. Submit for review Document tips: - Ensure documents are clearly readable - Submit full pages, not cropped images - Use color photos when possible - Avoid glare or shadows ## Bank Account Setup Configure where you receive payouts: 1. Go to **Finance > Account > Bank Details** 2. Click **Add Bank Account** 3. Enter bank account information: - Account holder name - Routing number - Account number - Account type (checking or savings) 4. Verify ownership (micro-deposits or instant verification) **Important:** Ensure bank account details are accurate. Incorrect information can delay payouts or result in failed transfers. ## Bank Verification Methods | Method | How It Works | Time | |--------|-------------|------| | **Instant Verification** | Log in to your bank to verify ownership | Immediate | | **Micro-deposits** | Two small deposits sent; you confirm amounts | 1-2 business days | ## Business Information Update your business profile: - **Business name** -- Legal and display names - **Business address** -- Registered address - **Business phone** -- Contact number - **Business website** -- Your website URL - **Industry** -- Business category - **Statement descriptor** -- What appears on customer statements ## Tax Information Provide tax information for reporting: - **Tax ID** -- EIN, SSN, or local equivalent - **Tax country** -- Where you are taxed - **VAT number** -- If applicable > RevKeen may be required to issue tax forms (1099-K in the US) based on your processing volume. Accurate information ensures correct reporting. ## Account Limits Your account may have processing limits based on verification status: | Limit Type | Description | |-----------|-------------| | **Monthly Volume** | Maximum processing per month | | **Per-Transaction** | Maximum single transaction amount | | **Payout Schedule** | How often you receive payouts | Limits increase automatically as you build processing history or can be raised by completing additional verification. --- # Analytics Source: https://docs.revkeen.com/docs/money/analytics Track revenue metrics, MRR, churn, and checkout conversion rates The Analytics dashboard provides deep insights into your business performance. Track revenue trends, understand customer behavior, and identify growth opportunities. ## Accessing Analytics Navigate to **Finance > Analytics** to view your analytics dashboard. Checkout-specific analytics are available under **Checkout > Analytics**. ## Revenue Metrics | Metric | Description | |--------|-------------| | **Gross Revenue** | Total revenue before any deductions | | **Net Revenue** | Revenue after refunds, chargebacks, and fees | | **MRR** | Monthly Recurring Revenue from subscriptions | | **ARR** | Annual Recurring Revenue (MRR x 12) | | **ARPU** | Average Revenue Per User | ## MRR Movements Track how your MRR changes over time: | Movement | Description | |----------|-------------| | **New MRR** | MRR from new subscriptions | | **Expansion MRR** | MRR increase from upgrades | | **Contraction MRR** | MRR decrease from downgrades | | **Churned MRR** | MRR lost from cancellations | | **Reactivation MRR** | MRR from reactivated subscriptions | ## Subscription Metrics | Metric | Description | |--------|-------------| | **Active Subscriptions** | Current number of active subscriptions | | **Churn Rate** | Percentage of subscriptions canceling per period | | **Trial Conversion** | Percentage of trials converting to paid | | **LTV** | Customer Lifetime Value | ## Charts and Visualizations Interactive charts help you understand trends: - **Revenue over time** -- Daily, weekly, or monthly view - **MRR waterfall** -- Visual breakdown of MRR changes - **Subscription growth** -- New vs churned over time - **Payment success rate** -- Transaction success trends - **Revenue by product** -- Top performing products - **Geographic distribution** -- Revenue by country ## Time Period Selection Analyze data across different time periods: - Last 7 days - Last 30 days - Last 90 days - Year to date - Custom date range > Compare periods to see growth. Select "Compare to previous period" to view percentage changes. ## Cohort Analysis Understand customer behavior over time: - **Retention cohorts** -- How long customers stay by signup month - **Revenue cohorts** -- Revenue generated by signup cohort - **Product cohorts** -- Behavior differences by first product ## Checkout Analytics Checkout Analytics helps you understand how customers move through your checkout flow, identify drop-off points, and optimize for higher conversion rates. ### Key Checkout Metrics | Metric | Description | |--------|-------------| | **Checkout Views** | Total times checkout page was loaded | | **Checkout Started** | Customers who began entering info | | **Payment Attempted** | Customers who clicked pay | | **Checkout Completed** | Successful purchases | | **Conversion Rate** | Completed / Views (percentage) | | **Abandonment Rate** | Started but not completed | ### Checkout Funnel Track customers through each step: 1. **Page View** -- Landed on checkout 2. **Email Entered** -- Provided email address 3. **Details Complete** -- Filled all required fields 4. **Payment Attempted** -- Clicked pay button 5. **Payment Successful** -- Transaction completed The funnel visualization shows where customers drop off so you can focus optimization efforts. ### Performance by Checkout Link Compare performance across different checkout links: - Revenue generated per link - Conversion rate per link - Average order value - Abandonment rate > Use this to identify which checkout links perform best and apply winning patterns to others. ### Device Breakdown Understand how device type affects conversions: | Device | Typical Insights | |--------|-----------------| | **Desktop** | Usually higher conversion, larger AOV | | **Mobile** | Higher traffic, may need optimization | | **Tablet** | Behavior between desktop and mobile | ### Payment Method Analytics See which payment methods customers prefer: - Usage percentage by payment method - Success rate by payment method - Average order value by method ### Traffic Sources Track where checkout traffic comes from: - **Direct** -- Direct link access - **Referral** -- From other websites - **UTM Source** -- Tagged marketing campaigns - **Ref parameter** -- Custom tracking codes Use UTM parameters to track marketing effectiveness: ``` https://checkout.revkeen.com/pay/xyz123 ?utm_source=facebook &utm_medium=paid &utm_campaign=summer-sale ``` ### Time to Convert Understand checkout duration: - **Average time** -- From page view to completion - **Time per step** -- Duration at each stage - **Optimal range** -- Target checkout time > Longer checkout times often indicate friction. Look for steps that take unusually long. ### Failure Analysis Understand why payments fail: | Failure Reason | Possible Actions | |----------------|-----------------| | **Card declined** | Suggest trying another card | | **Insufficient funds** | Offer payment plans if available | | **Invalid card** | Improve input validation | | **3D Secure failed** | Clear authentication instructions | | **Fraud blocked** | Review fraud rules | ### Optimization Opportunities Use analytics to identify improvements: - **High abandonment at email** -- Consider guest checkout - **Drop-off at address** -- Minimize required fields - **Failed payments** -- Add more payment methods - **Mobile issues** -- Optimize mobile experience - **Long checkout time** -- Simplify the flow ## Exporting Reports Export data for further analysis: 1. Select the report or chart 2. Click **Export** 3. Choose format (CSV, Excel, or PDF) 4. Download the report ## Scheduled Reports Automatically receive reports via email: 1. Configure the report parameters 2. Click **Schedule** 3. Set frequency (daily, weekly, monthly) 4. Add email recipients 5. Save the schedule --- # Disputes Source: https://docs.revkeen.com/docs/money/disputes Monitor chargebacks and dispute resolutions from the finance perspective The Disputes dashboard helps you manage chargebacks and payment disputes. Respond with evidence, track outcomes, and understand dispute patterns. ## Accessing Disputes Navigate to **Finance > Disputes** to view all disputes. ## What is a Dispute? A dispute (chargeback) occurs when a customer contacts their bank to reverse a charge. Common reasons include: - Customer does not recognize the charge - Product or service not received - Product significantly different than described - Unauthorized transaction (fraud) - Duplicate or incorrect charge ## Dispute List View all disputes with key information: | Column | Description | |--------|-------------| | **Date Opened** | When the dispute was filed | | **Customer** | Who filed the dispute | | **Amount** | Disputed amount | | **Reason** | Dispute category | | **Evidence Due** | Deadline to submit evidence | | **Status** | Current dispute status | ## Dispute Status | Status | Description | Action Required | |--------|-------------|-----------------| | `Needs Response` | Awaiting your evidence | Submit evidence before deadline | | `Under Review` | Bank reviewing evidence | Wait for decision | | `Won` | Resolved in your favor | Funds returned | | `Lost` | Customer won the dispute | Funds not returned | ## Responding to Disputes **Important:** Evidence must be submitted before the deadline. Missing the deadline results in automatic loss. 1. Open the dispute 2. Review the dispute details and reason 3. Gather relevant evidence 4. Upload evidence files 5. Write a response explaining your case 6. Submit before the deadline ## Recommended Evidence Evidence depends on the dispute reason: | Dispute Reason | Helpful Evidence | |---------------|-----------------| | **Fraudulent** | AVS/CVV match, IP address, prior purchases, delivery confirmation | | **Product not received** | Shipping/tracking info, delivery confirmation, signed receipt | | **Not as described** | Product descriptions, images, customer communications | | **Duplicate** | Proof transactions were separate, itemized receipts | | **Subscription canceled** | Cancellation policy, customer acknowledgment, usage logs | > RevKeen automatically includes transaction details, customer information, and invoice copies with your evidence submission. ## Financial Impact When a dispute is opened: - **Disputed amount** -- Immediately deducted from your balance - **Dispute fee** -- Additional fee charged by the bank (typically $15-25) - **If won** -- Disputed amount returned, but fee usually not refunded - **If lost** -- Amount stays with customer ## Preventing Disputes Reduce chargebacks with these practices: - **Clear billing descriptor** -- Use recognizable business name - **Order confirmations** -- Send detailed receipts - **Shipping notifications** -- Provide tracking information - **Easy refunds** -- Process refunds promptly when appropriate - **Customer service** -- Make it easy to reach you - **Clear policies** -- Document cancellation and refund terms ## Dispute Metrics Track your dispute performance: | Metric | Description | Target | |--------|-------------|--------| | **Dispute Rate** | Disputes / Total transactions | < 1% | | **Win Rate** | Disputes won / Total disputes | > 50% | | **Response Rate** | Responded / Total requiring response | 100% | **Important:** High dispute rates can result in increased processing fees or account termination. Monitor and address trends promptly. ## Related - [Disputes (Billing Guide)](/docs/using-revkeen/disputes) -- How to respond to chargebacks and submit evidence - [Payments and Refunds](/docs/using-revkeen/payments-and-refunds) -- Processing refunds to avoid disputes - [Refunds](/docs/money/refunds) -- Track refund status and financial impact --- # How Fees Work Source: https://docs.revkeen.com/docs/money/how-fees-work Understand RevKeen pricing, transaction fees, and billing RevKeen is designed with straightforward pricing. This page explains the fee structure so you know exactly what you are paying for. ## Fee Overview There are two categories of fees when using RevKeen: 1. **RevKeen platform fees** -- The subscription and/or per-transaction fees for using the RevKeen platform. 2. **Payment processing fees** -- The fees charged by your payment gateway (such as NMI or Elavon) for processing each transaction. These are separate charges. RevKeen platform fees cover the software, dashboard, analytics, and automation. Payment processing fees go to the gateway and card networks. ## Transaction Fees **RevKeen platform fee: 1.7% + £0.10 per transaction** (all plans). This is the same rate on Standard, Pro, and Unlimited. There is no per-plan variation in transaction fees. On top of the RevKeen platform fee, your payment processor charges their own fees: | Component | Description | |-----------|-------------| | **Gateway processing fee** | Percentage + fixed fee charged by your payment processor (e.g., Elavon, NMI) | | **Card network fee** | Interchange and assessment fees from Visa, Mastercard, etc. | | **RevKeen platform fee** | **1.7% + £0.10** per successful transaction | Your total processing cost = gateway fees + RevKeen platform fee. ## How Fees Are Deducted Fees are deducted from each payout before funds reach your bank account: 1. Customer pays $100 2. Gateway processing fee is deducted (e.g., 2.9% + $0.30 = $3.20) 3. RevKeen platform fee is deducted (if applicable on your plan) 4. Net amount is included in your next payout You can see the fee breakdown for every transaction in the [Income](/docs/money/income) dashboard. ## Subscription Plans RevKeen offers three plans. The transaction fee (1.7% + £0.10) is the same on all plans. | | **Standard** | **Pro** | **Unlimited** | |---|:---:|:---:|:---:| | **Monthly fee** | £69 | £119 | £199 | | **Transactions** | 150/month | 450/month | Unlimited | | **Invoices** | 10/month | 100/month | Unlimited | | **Dashboard** | Basic | Full | Full | | **Reporting** | Basic | Advanced | Advanced | | **WhatsApp** | -- | Yes | Yes | | **AI Inbox Pro** | -- | -- | Yes | No hidden costs, no contracts, cancel anytime. See [revkeen.com/pricing](https://revkeen.com/pricing) for full details. ## What Is Included Every RevKeen plan includes: - Full dashboard with analytics and reporting - Hosted checkout pages - Invoice and subscription management - Customer portal - Email notifications - Webhook integrations - Multi-user access with role-based permissions - PCI-compliant payment handling ## Refund Fees When you issue a refund: - The **full amount** is returned to the customer - The **original processing fee** is typically not refunded by the gateway - RevKeen does not charge an additional fee for processing refunds This means refunds cost you the original processing fee. Voids (same-day reversals before settlement) avoid this cost entirely because the transaction is canceled before fees are assessed. ## Chargeback Fees When a customer files a dispute (chargeback): - The **disputed amount** is immediately held from your balance - A **chargeback fee** (typically $15-25) is charged by the bank - If you **win** the dispute, the disputed amount is returned, but the chargeback fee usually is not - If you **lose**, both the amount and fee are permanent See [Disputes](/docs/money/disputes) for how to respond to and prevent chargebacks. ## No Hidden Fees RevKeen does not charge: - Setup fees - Cancellation fees - PCI compliance fees - Monthly minimum fees - Batch processing fees ## Viewing Your Fees To review fees: - **Per transaction** -- Open any transaction in [Income](/docs/money/income) to see the fee breakdown - **Per payout** -- Open any payout in [Payouts](/docs/money/payouts) to see total fees deducted - **Over time** -- Use [Analytics](/docs/money/analytics) to track fee trends relative to revenue --- # Income Source: https://docs.revkeen.com/docs/money/income View transaction history, revenue breakdown, and income reports The Income dashboard provides a complete view of all payments received. Track individual transactions, understand revenue composition, and reconcile with your payment processors. ## Accessing Income Navigate to **Finance > Income** to view all transactions. ## Transaction List The list shows all successful payments: | Column | Description | |--------|-------------| | **Date** | When the payment was received | | **Customer** | Who made the payment | | **Description** | Invoice number or product name | | **Amount** | Gross payment amount | | **Fees** | Processing fees deducted | | **Net** | Amount after fees | | **Status** | Paid, refunded, disputed | ## Filtering Transactions Find specific transactions using filters: - **Date range** -- Payments within a period - **Customer** -- Payments from specific customer - **Amount** -- Minimum or maximum amount - **Status** -- Paid, refunded, or disputed - **Payment method** -- Card, ACH, etc. - **Product** -- Payments for specific product ## Summary Metrics The header shows totals for the selected period: | Metric | Description | |--------|-------------| | **Gross Income** | Total payments before fees | | **Total Fees** | Sum of all processing fees | | **Net Income** | Gross minus fees | | **Transaction Count** | Number of successful payments | | **Average Transaction** | Mean payment amount | ## Transaction Details Click any transaction to view full details: - **Payment details** -- Amount, currency, fees - **Payment method** -- Card type, last 4 digits - **Related invoice** -- Link to the invoice paid - **Customer info** -- Link to customer profile - **Gateway response** -- Transaction ID, authorization - **Timeline** -- Payment events and status changes ## Understanding Fees Processing fees vary by payment method: | Payment Method | Typical Fee Structure | |---------------|----------------------| | **Credit Cards** | Percentage + fixed fee per transaction | | **Debit Cards** | Usually lower than credit cards | | **ACH/Bank Transfer** | Fixed fee or percentage with cap | > Exact fees depend on your payment gateway agreement. View fee details in each transaction. ## Revenue by Source Break down income by source: - **By product** -- Revenue per product - **By customer** -- Top customers by revenue - **By payment method** -- Card vs ACH breakdown - **By checkout link** -- Revenue per link ## Exporting Income Data Export transactions for accounting or analysis: 1. Set your date range and filters 2. Click **Export** 3. Choose format: - **CSV** -- For spreadsheets - **PDF** -- For reports - **QuickBooks format** -- For accounting software 4. Download the file ## Reconciliation Match RevKeen data with your bank statements: - Use the payout reference to match bank deposits - Filter by payout to see included transactions - Export for detailed reconciliation --- # Payouts Source: https://docs.revkeen.com/docs/money/payouts Track when processed payments are deposited to your bank account The Payouts dashboard shows when collected funds are deposited to your bank account. Track payout schedules, reconcile deposits, and understand your cash flow. ## Accessing Payouts Navigate to **Finance > Payouts** to view all payouts. ## Payout List View all payouts with key information: | Column | Description | |--------|-------------| | **Date** | When payout was initiated | | **Arrival Date** | Expected bank deposit date | | **Amount** | Net amount deposited | | **Status** | Pending, in transit, paid, failed | | **Bank Account** | Destination account (last 4 digits) | ## Payout Status | Status | Description | |--------|-------------| | `Pending` | Payout scheduled but not yet initiated | | `In Transit` | Funds being transferred to bank | | `Paid` | Successfully deposited to bank | | `Failed` | Payout failed (check bank details) | ## Payout Schedule Payouts are made on a regular schedule based on your gateway settings: | Schedule | Description | |----------|-------------| | **Daily** | Payouts every business day | | **Weekly** | Payouts once per week | | **Monthly** | Payouts once per month | > Payout timing depends on your payment gateway and bank. Most payouts arrive within 1-2 business days after initiation. ## Payout Details Click any payout to see what is included: - **Summary** -- Gross, fees, refunds, net - **Transactions** -- All payments in this payout - **Refunds** -- Refunds deducted from this payout - **Fees** -- Processing fees breakdown - **Adjustments** -- Any chargebacks or corrections ## Payout Breakdown Each payout consists of: | Component | Impact | |-----------|--------| | **+ Gross Payments** | Total payments collected | | **- Processing Fees** | Gateway and card fees | | **- Refunds** | Refunds issued | | **- Chargebacks** | Dispute losses and fees | | **+/- Adjustments** | Corrections or reserves | | **= Net Payout** | Amount deposited | ## Bank Account Settings Configure your payout destination: 1. Go to **Finance > Account** 2. Click **Bank Details** 3. Add or update bank account information 4. Verify with micro-deposits if required ## Filtering Payouts Find specific payouts using filters: - **Date range** -- Payouts within a period - **Status** -- Pending, paid, or failed - **Amount** -- Minimum or maximum amount ## Exporting Payouts Export payout data for reconciliation: 1. Select date range 2. Click **Export** 3. Choose format (CSV or PDF) 4. Download for bank reconciliation --- # Refunds Source: https://docs.revkeen.com/docs/money/refunds Issue full or partial refunds and track refund status The Refunds dashboard lets you issue and track refunds. Process full or partial refunds, understand their impact on your revenue, and maintain customer satisfaction. > For same-day reversals before settlement, RevKeen automatically performs a **void** instead of a refund. Voids release the hold without moving funds and avoid processing fees. See [Payments and Refunds](/docs/using-revkeen/payments-and-refunds) for details on void vs refund. ## Accessing Refunds Navigate to **Finance > Refunds** to view all refunds. ## Refund List View all refunds with key information: | Column | Description | |--------|-------------| | **Date** | When refund was issued | | **Customer** | Who received the refund | | **Original Payment** | Payment being refunded | | **Amount** | Refund amount | | **Reason** | Refund reason (if provided) | | **Status** | Pending, succeeded, failed | ## Issuing a Refund Refunds can be issued from multiple places. ### From Finance > Refunds 1. Click **New Refund** 2. Search for the payment to refund 3. Select full or partial refund 4. Enter refund amount (for partial) 5. Add a reason 6. Click **Issue Refund** ### From Invoice or Order 1. Open the paid invoice or order 2. Click **Refund** 3. Select full or partial refund 4. Enter refund amount (for partial) 5. Add a reason 6. Click **Issue Refund** ## Full vs Partial Refunds | Type | Description | Use Case | |------|-------------|----------| | **Full Refund** | Returns entire payment amount | Complete cancellation, wrong product | | **Partial Refund** | Returns a specified amount | Partial service, discount after purchase | > Multiple partial refunds can be issued on a single payment, up to the total payment amount. ## Refund Status | Status | Description | |--------|-------------| | `Pending` | Refund is being processed | | `Succeeded` | Refund completed successfully | | `Failed` | Refund could not be processed | ## Refund Timing How long refunds take to appear for customers: | Payment Method | Typical Time | |---------------|-------------| | **Credit Card** | 5-10 business days | | **Debit Card** | 5-10 business days | | **ACH** | 3-5 business days | **Important:** Refund timing depends on the customer's bank. RevKeen processes refunds immediately, but banks may take additional time to credit the account. ## Refund Reasons Common refund reasons to track: - **Duplicate charge** -- Customer charged twice - **Product not delivered** -- Fulfillment issue - **Product unsatisfactory** -- Quality concern - **Customer request** -- Changed mind - **Subscription cancellation** -- Prorated refund - **Fraud** -- Unauthorized transaction ## Impact on Revenue How refunds affect your finances: - **Gross revenue** -- No change (reflects original transaction) - **Net revenue** -- Reduced by refund amount - **Processing fees** -- Usually not returned on refunds - **Payouts** -- Deducted from next payout > Most payment processors do not return the original processing fee when you issue a refund. ## Filtering Refunds Find specific refunds using filters: - **Date range** -- Refunds within a period - **Customer** -- Refunds for specific customer - **Amount** -- Minimum or maximum amount - **Reason** -- Filter by refund reason - **Status** -- Pending, succeeded, or failed ## Related - [Payments and Refunds](/docs/using-revkeen/payments-and-refunds) -- Full guide to processing refunds, credit notes, and void vs refund logic - [Disputes](/docs/using-revkeen/disputes) -- Handle chargebacks and payment disputes - [How Fees Work](/docs/money/how-fees-work) -- Understand refund fee impact --- # Tax Source: https://docs.revkeen.com/docs/money/tax Automate tax calculation and reporting with Quaderno integration RevKeen integrates with Quaderno to automate tax calculation, collection, and reporting. Whether you need to handle VAT, sales tax, or GST, the tax system applies the correct rates at checkout and keeps your reporting up to date. ## How Tax Works in RevKeen Tax calculation happens automatically at key points in the payment lifecycle: 1. **At checkout** -- When a customer reaches the payment page, RevKeen determines the applicable tax rate based on the customer's location, your business location, and the product type. 2. **On invoices** -- Tax is calculated and itemized on every invoice, showing the tax rate, taxable amount, and tax total. 3. **On subscription renewals** -- Each renewal recalculates tax in case rates or customer details have changed. ## Quaderno Integration RevKeen uses Quaderno as its tax engine. Quaderno handles: - **Tax rate lookup** -- Determines the correct VAT, sales tax, or GST rate based on jurisdiction - **Tax validation** -- Validates VAT numbers for B2B reverse-charge transactions in the EU - **Tax receipts** -- Generates compliant tax invoices and credit notes - **Tax reporting** -- Aggregates tax collected by jurisdiction for filing ## Supported Tax Types | Tax Type | Regions | Notes | |----------|---------|-------| | **VAT** | EU, UK | Includes reverse-charge for valid VAT numbers | | **Sales Tax** | US, Canada | State and provincial rates | | **GST** | Australia, New Zealand, India | Goods and Services Tax | ## Tax at Checkout When a customer checks out, the tax calculation follows these steps: 1. Customer enters their billing address (or location is detected) 2. RevKeen sends the product, amount, and location to Quaderno 3. Quaderno returns the applicable tax rate 4. The tax amount is displayed to the customer before payment 5. The total (amount + tax) is charged For B2B transactions in the EU, customers can enter their VAT number. If valid, the reverse-charge mechanism applies and no VAT is collected. ## Tax on Invoices Every invoice includes tax details: - **Subtotal** -- Amount before tax - **Tax rate** -- The percentage applied - **Tax amount** -- Calculated tax - **Total** -- Subtotal + tax Tax is shown as a separate line item so customers see exactly what they are paying. ## Tax Reporting Quaderno aggregates all tax collected and provides reports by jurisdiction. Use these reports to: - File VAT returns in EU countries where you have obligations - Report sales tax collected by US state - Track GST obligations in applicable countries ## Setup To enable automatic tax calculation: 1. Go to **Settings > Integrations** 2. Connect your Quaderno account 3. Configure your business tax details (tax ID, business address, registration numbers) 4. Set product tax categories (digital services, physical goods, etc.) 5. Enable tax calculation on your checkout links Once configured, tax is calculated automatically on all new transactions. ## Tax Exemptions Some transactions may be tax-exempt: - **B2B with valid VAT number** -- Reverse-charge applies in the EU - **Tax-exempt customers** -- Customers with exemption certificates - **Exempt product categories** -- Certain goods or services may be exempt in specific jurisdictions To mark a customer as tax-exempt, update their profile in the customer settings. ## Related - [Quaderno Integration](/docs/integrations/quaderno) -- Setup, configuration, and VAT pool details for the Quaderno tax engine - [How Fees Work](/docs/money/how-fees-work) -- Understand the full cost structure including tax handling --- # Operations Source: https://docs.revkeen.com/docs/operations Manage your team, configure settings, and monitor platform events The Operations section covers everything you need to run your RevKeen account day to day -- from managing your team and configuring settings to monitoring activity and staying on top of notifications. ## What you'll find here - **[Team Management](/docs/operations/team-management)** -- Invite team members, assign roles, and control who can access what - **[Settings](/docs/operations/settings)** -- Configure your merchant profile, business information, branding, and platform preferences - **[Notifications](/docs/operations/notifications)** -- View and manage alerts, payment notifications, and system messages from your inbox - **[Events](/docs/operations/events)** -- Track every action across your account with a full activity timeline and audit trail ## Dashboard overview When you log into RevKeen, the Home dashboard provides an at-a-glance view of your business health, including revenue metrics, recent activity, and quick actions to manage your day-to-day operations. ### Key metrics | Metric | Description | |--------|-------------| | **Gross Revenue** | Total revenue before refunds and fees | | **Net Revenue** | Revenue after refunds, fees, and chargebacks | | **MRR** | Monthly Recurring Revenue from active subscriptions | | **Active Customers** | Customers with active subscriptions or recent purchases | | **Churn Rate** | Percentage of subscriptions cancelled this period | | **Average Order Value** | Mean transaction amount across all orders | ### Time period selection Use the date picker to view metrics for different time periods: - **Today** -- Current day's activity - **Last 7 days** -- Rolling weekly view - **Last 30 days** -- Monthly overview - **This month** -- Calendar month to date - **Last month** -- Previous calendar month - **Custom range** -- Select specific start and end dates ### Quick actions The Home dashboard provides shortcuts for common tasks: - **Create Invoice** -- Generate a new invoice for a customer - **Add Customer** -- Create a new customer record - **New Checkout Link** -- Create a shareable payment link - **View Reports** -- Access detailed analytics and reports ### Recent activity feed The activity feed shows real-time updates including: - New customer sign-ups - Successful payments - Failed payment attempts - Subscription changes (upgrades, downgrades, cancellations) - Refund requests - Chargeback notifications > **Note:** Click any activity item to view full details and take action if needed. ### Pending actions Items requiring your attention are highlighted on the dashboard: | Action Type | Description | |-------------|-------------| | **Draft Invoices** | Invoices ready to be finalized and sent | | **Failed Payments** | Payments that need retry or customer follow-up | | **Open Disputes** | Chargebacks requiring evidence submission | | **Pending Refunds** | Refund requests awaiting approval | ## Next steps - [Team Management](/docs/operations/team-management) -- Set up your team and assign roles - [Settings](/docs/operations/settings) -- Configure your merchant profile and preferences - [Notifications](/docs/operations/notifications) -- Manage your inbox and alert preferences - [Events](/docs/operations/events) -- Monitor activity across your account --- # Events Source: https://docs.revkeen.com/docs/operations/events Track activity across your account with the event timeline and audit trail Events provide a complete audit trail of everything that happens in your RevKeen account. Every action -- from customer creation to payment processing -- generates an event that you can view, filter, and react to via webhooks. ## What is an event? An event is a record of something that happened in your account. Each event includes: - **What happened** -- The event type (e.g., `payment.succeeded`) - **When it happened** -- Timestamp - **What was affected** -- Related entities (customer, invoice, etc.) - **Event data** -- Snapshot of the object at event time ## Viewing events in the dashboard Navigate to **Sales > Events** to view the event stream. Events are displayed in reverse chronological order. ### Event stream columns | Column | Description | |--------|-------------| | **Event Type** | What happened (e.g., `payment.succeeded`) | | **Object** | Affected entity (customer, invoice, etc.) | | **Time** | When the event occurred | | **Webhook Status** | Delivery status to your webhooks | ### Filtering events Use filters to find specific events: - **Event type** -- Filter by category or specific type - **Date range** -- Events within a time period - **Related object** -- Events for a specific customer, invoice, etc. - **Webhook status** -- Delivered, failed, or pending ### Event details Click any event to view full details: - **Event ID** -- Unique identifier - **Timestamp** -- Exact time of occurrence - **Event data** -- Full payload (JSON) - **Related objects** -- Links to customer, invoice, etc. - **Webhook deliveries** -- Status of each webhook attempt ### Events by object View events for a specific object: 1. Open any customer, invoice, subscription, etc. 2. Click the **Events** tab 3. See all events related to that object ## Event categories ### Checkout events | Event Type | Description | |------------|-------------| | `checkout.started` | Customer began checkout process | | `checkout.completed` | Checkout completed successfully | | `checkout.expired` | Checkout session expired | | `checkout.abandoned` | Customer left without completing | ### Invoice events | Event Type | Description | |------------|-------------| | `invoice.created` | Invoice was created | | `invoice.finalized` | Invoice was finalized (no longer editable) | | `invoice.sent` | Invoice email sent to customer | | `invoice.paid` | Invoice was paid in full | | `invoice.payment_failed` | Payment attempt failed | | `invoice.voided` | Invoice was cancelled/voided | | `invoice.marked_uncollectible` | Invoice written off as bad debt | | `invoice.reminder_sent` | Payment reminder email sent | ### Order events | Event Type | Description | |------------|-------------| | `order.created` | Order was created | | `order.paid` | Order payment received | | `order.fulfilled` | All items fulfilled | | `order.partially_fulfilled` | Some items fulfilled | | `order.canceled` | Order was cancelled | ### Subscription events | Event Type | Description | |------------|-------------| | `subscription.created` | Subscription was created | | `subscription.activated` | Subscription became active (trial ended or first payment) | | `subscription.renewed` | Subscription renewed for new period | | `subscription.paused` | Subscription was paused | | `subscription.resumed` | Paused subscription was resumed | | `subscription.canceled` | Subscription was cancelled | | `subscription.trial_ended` | Trial period ended | ### Payment events | Event Type | Description | |------------|-------------| | `payment.attempted` | Payment attempt was made | | `payment.succeeded` | Payment was successful | | `payment.failed` | Payment failed | | `payment.refunded` | Payment was refunded | | `payment.voided` | Authorization was voided | ### Chargeback events | Event Type | Description | |------------|-------------| | `chargeback.opened` | Chargeback/dispute was opened | | `chargeback.evidence_submitted` | Evidence was submitted | | `chargeback.won` | Chargeback resolved in your favor | | `chargeback.lost` | Chargeback resolved against you | ### Customer events | Event Type | Description | |------------|-------------| | `customer.created` | Customer was created | | `customer.updated` | Customer details were updated | | `customer.payment_method.attached` | Payment method was added | | `customer.payment_method.detached` | Payment method was removed | ## Event data structure Each event contains the following fields: | Field | Description | |-------|-------------| | `id` | Unique event identifier | | `type` | Event type (e.g., `invoice.paid`) | | `created_at` | When the event occurred | | `data` | Snapshot of the affected object | | `entities` | Related entity references (customer, invoice, etc.) | ## Reacting to events with webhooks Configure webhooks to receive real-time notifications when events occur: 1. Go to **Settings > Webhooks** 2. Create a webhook endpoint 3. Select which event types to receive 4. RevKeen sends HTTP POST requests to your endpoint > **Note:** Webhooks are the recommended way to sync RevKeen data with your systems. See the [Webhooks documentation](/docs/webhooks) for details. ## Webhook delivery status For each event, you can see the webhook delivery status: | Status | Description | |--------|-------------| | **Delivered** | Webhook received 2xx response | | **Pending** | Awaiting delivery or retry | | **Failed** | All retry attempts exhausted | > **Note:** Click **Retry** on failed deliveries to resend the webhook manually. ## Using events for debugging The event stream helps you debug issues: - **Payment failures** -- See `payment.failed` events with error details - **Webhook issues** -- Check delivery logs and response codes - **Customer activity** -- Trace all events for a customer - **Timeline reconstruction** -- Understand sequence of events ## Exporting events Export events for external analysis: 1. Apply filters for the events you need 2. Click **Export** 3. Choose format (CSV or JSON) 4. Download the export file ## Event retention Events are retained for historical reference: - Full event data available for 30 days - Event metadata retained indefinitely - Export important events for long-term storage ## Next steps - [Notifications](/docs/operations/notifications) -- Manage in-app notification preferences - [Settings](/docs/operations/settings) -- Configure webhook endpoints in settings --- # Notifications Source: https://docs.revkeen.com/docs/operations/notifications View and manage alerts, payment notifications, and system messages The Inbox consolidates all notifications, alerts, and updates from across RevKeen into a single location. Stay informed about important events and take action directly from your inbox. ## What appears in your inbox Your inbox receives notifications across several categories: | Category | Notification Types | |----------|--------------------| | **Payments** | Successful payments, failed payments, payment retries | | **Subscriptions** | New subscriptions, cancellations, renewals, trial endings | | **Invoices** | Invoice created, paid, overdue, voided | | **Customers** | New customers, profile updates, payment method changes | | **Disputes** | Chargeback opened, evidence due, dispute resolved | | **System** | Webhook failures, integration issues, security alerts | ## Notification categories ### Action required High-priority items that need your attention: - Chargebacks requiring evidence submission - Failed payments needing manual intervention - Expiring payment methods - KYC verification requests - Webhook endpoint failures ### Informational Updates to keep you informed: - Successful payment confirmations - New customer registrations - Subscription renewals - Payout completions ## Managing notifications ### Filtering Filter your inbox by: - **All** -- View all notifications - **Unread** -- Only unread items - **Action Required** -- Items needing attention - **Category** -- Payments, subscriptions, customers, etc. ### Actions Available actions for notifications: - **Mark as read** -- Dismiss the notification - **View details** -- Open the related object (invoice, customer, etc.) - **Take action** -- Perform the required action directly - **Archive** -- Remove from active inbox ## Notification preferences Configure which notifications you receive and how: 1. Go to **Settings > Notifications** 2. Toggle notification types on/off 3. Configure email digest preferences 4. Set up Slack integration for real-time alerts > **Note:** Critical notifications (chargebacks, security alerts) cannot be disabled to ensure you never miss important events. ## Email notifications In addition to in-app notifications, you can receive email alerts: | Email Type | Description | |------------|-------------| | **Instant alerts** | Immediate email for critical events (disputes, large payments) | | **Daily digest** | Summary of the day's activity sent each morning | | **Weekly summary** | Weekly business performance overview | ## Slack integration Connect RevKeen to Slack for real-time notifications: 1. Go to **Apps > Slack** 2. Click **Connect to Slack** 3. Select the channel for notifications 4. Choose which events to send to Slack ## Next steps - [Events](/docs/operations/events) -- View the full activity timeline and audit trail - [Settings](/docs/operations/settings) -- Configure notification preferences in general settings --- # Settings Source: https://docs.revkeen.com/docs/operations/settings Configure your merchant profile, general settings, and custom fields Settings let you configure your account preferences, business information, branding, and platform-wide options that affect how RevKeen works for you and your customers. ## General settings Navigate to **Settings > General** in the sidebar to access general account configuration. ### Business information Configure your business details that appear on invoices, checkout pages, and customer communications: | Setting | Description | |---------|-------------| | **Business Name** | Your legal business name | | **Display Name** | Name shown to customers | | **Business Address** | Registered business address | | **Support Email** | Email for customer inquiries | | **Support Phone** | Phone number for customers | | **Website URL** | Your business website | ### Branding Customize your brand appearance across checkout pages, invoices, emails, and the customer portal: - **Logo** -- Upload your business logo (used on invoices, checkout) - **Favicon** -- Small icon for browser tabs - **Brand Color** -- Primary color for buttons and accents - **Accent Color** -- Secondary color for highlights > **Note:** Brand settings apply to checkout pages, invoices, emails, and the customer portal. ### Currency and localization | Setting | Description | |---------|-------------| | **Default Currency** | Primary currency for new products | | **Timezone** | Used for scheduling and reporting | | **Date Format** | How dates are displayed | | **Language** | Dashboard language preference | ### Invoice settings Customize invoice defaults: - **Invoice Prefix** -- Prefix for invoice numbers (e.g., `INV-`) - **Next Invoice Number** -- Starting number for invoices - **Default Due Days** -- Days until invoice is due - **Default Footer** -- Text that appears on all invoices - **Default Memo** -- Note to include on invoices ### Email settings Configure outgoing email behavior: | Setting | Description | |---------|-------------| | **From Name** | Name shown in email sender field | | **Reply-To Email** | Where customer replies go | | **BCC Email** | Receive copies of all customer emails | ### Payment settings Configure payment behavior: - **Statement Descriptor** -- What appears on customer credit card statements - **Auto-finalize Invoices** -- Automatically finalize draft invoices - **Auto-charge Invoices** -- Automatically charge when invoice is due > **Note:** Use a recognizable statement descriptor to reduce chargebacks. Include your business name or URL so customers recognize the charge. ### Wallet payment methods (Apple Pay and Google Pay) Enable digital wallet payments on your checkout pages. Navigate to **Settings > Checkout Appearance** to configure: | Setting | Description | |---------|-------------| | **Apple Pay** | Enable Apple Pay on checkout (Safari on macOS/iOS) | | **Google Pay** | Enable Google Pay on checkout (all major browsers) | When enabled, customers see wallet payment tabs alongside the standard card form. Wallet buttons only appear on supported devices. > **Note:** Apple Pay requires your NMI gateway to have Apple Pay enabled. Contact your payment processor if you need to activate it. No additional domain verification is required -- RevKeen handles this automatically. Apple Pay cannot be used for auto-charge subscriptions because wallet tokens are one-time use and cannot be saved for recurring billing. Customers will be prompted to use a card for these products. ### Subscription settings Default settings for subscriptions: | Setting | Description | |---------|-------------| | **Proration Behavior** | How to handle mid-cycle upgrades/downgrades | | **Collection Method** | Auto-charge or send invoice | | **Days Until Due** | For invoiced subscriptions | ### Notification preferences Control which notifications you receive: - **Payment notifications** -- Successful payments, failures - **Subscription events** -- New, canceled, past due - **Dispute alerts** -- Chargeback notifications - **Daily/weekly digests** -- Summary emails ### Data export Export your RevKeen data: 1. Go to **Settings > General > Data Export** 2. Select what to export (customers, invoices, subscriptions, etc.) 3. Choose date range 4. Click **Export** 5. Download the CSV file --- ## Profile settings Access your profile settings by clicking your avatar in the top-right corner and selecting **My Profile**, or navigate to **Settings > Profile** in the sidebar. Profile settings are specific to your user account and do not affect your organization's business settings. ### Profile photo Add a profile photo to personalize your account and help team members identify you. | Requirement | Details | |-------------|---------| | **Supported Formats** | JPEG, PNG, GIF, WebP | | **Maximum Size** | 2 MB | | **Recommended** | Square image, at least 200x200 pixels | To upload or change your profile photo: 1. Click **Upload Photo** in the Profile Photo section 2. Select an image file from your device 3. The photo will be uploaded and saved automatically > **Note:** If you do not upload a photo, your initials will be displayed as your avatar. ### Personal information Update your personal details that are displayed across the platform: | Field | Description | Editable | |-------|-------------|----------| | **Full Name** | Your display name shown to team members and in activity logs | Yes | | **Email Address** | Your login email and where notifications are sent | Contact support | | **Phone Number** | Contact number for account recovery and notifications | Yes | | **Job Title** | Your role or position within your organization | Yes | To update your profile information: 1. Navigate to your Profile Settings 2. Edit the fields you want to update 3. Click **Save Changes** 4. You will see a confirmation message when saved successfully > **Note:** Changes to your profile are reflected immediately across the platform, including in team activity logs and notifications. ### Changing your email For security reasons, email address changes require verification: 1. Contact the support team with your request 2. Verify ownership of both your current and new email addresses 3. Once verified, your email will be updated ### Security RevKeen uses **passwordless magic link authentication**. When you sign in, a secure link is sent to your email address. There is no password to manage or remember. If you need to change the email address associated with your account, see the "Changing your email" section above. ### Profile best practices - Use a professional photo that clearly shows your face - Keep your contact information up to date for account recovery - Use your real name so team members can easily identify you - Add your job title to help others understand your role --- ## Custom fields Navigate to **Settings > Custom Fields** to manage your fields. Custom fields allow you to capture additional information on customers, orders, and subscriptions that is specific to your business needs. ### What are custom fields? Custom fields let you store additional data on RevKeen objects: - **Customers** -- Industry, company size, account manager - **Orders** -- Special instructions, project codes, PO numbers - **Subscriptions** -- Contract ID, renewal notes - **Checkout** -- Collect info during checkout (license plate, T-shirt size) ### Supported entities | Entity | Description | |--------|-------------| | **Customer** | Fields appear on customer profiles | | **Order** | Fields appear on one-time orders | | **Subscription** | Fields appear on subscriptions | | **Checkout** | Fields collected during checkout | ### Field types | Type | Description | Use Case | |------|-------------|----------| | **Text** | Single line text input | Names, IDs, short notes | | **Textarea** | Multi-line text input | Descriptions, instructions | | **Number** | Numeric input | Quantities, scores, employee count | | **Select** | Dropdown with predefined options | Categories, industries, status | | **Multi-Select** | Multiple selections allowed | Tags, features, interests | | **Date** | Date picker | Birthdays, contract dates | | **Checkbox** | Yes/No toggle | Opt-ins, confirmations | ### Creating a custom field 1. Click **Add Field** 2. Select the entity (Customer, Order, etc.) 3. Enter a field name 4. Select the field type 5. Configure options: - **Required** -- Must be filled - **Visible to customer** -- Shown on portal/checkout - **Editable by customer** -- Customer can update 6. For Select/Multi-Select, add the options 7. Click **Create Field** > **Note:** Field names become machine-readable keys. Use descriptive names that work well in your code (e.g., `company_size` instead of `Size`). ### Checkout custom fields Collect information during checkout: 1. Create a custom field with entity type "Checkout" 2. Mark it as required if needed 3. The field appears on the checkout page 4. Data is stored with the order or subscription Common checkout fields: - T-shirt size - Dietary restrictions - License plate number - Purchase order number - Gift message ### Viewing custom field data Custom field values appear: - On the entity detail page (Customer, Order, etc.) - In list views (enable column) - In exports (CSV, reports) - Via API in the metadata object - In webhook payloads ### Filtering by custom fields Use custom fields to filter lists: 1. Go to the entity list (Customers, Orders, etc.) 2. Click **Filters** 3. Select your custom field 4. Enter the filter value 5. Apply the filter ### Editing custom fields You can modify certain field properties after creation: | Property | Editable? | Notes | |----------|-----------|-------| | Display name | Yes | Rename anytime | | Required | Yes | Only affects new entries | | Visibility | Yes | Show/hide from customers | | Field type | No | Cannot change after creation | | Options (Select) | Add only | Can add options, not remove | ### Deleting custom fields To delete a custom field: 1. Click the field to edit 2. Click **Delete Field** 3. Confirm deletion > **Note:** Deleting a field removes it from the interface but existing data is preserved in the metadata. You can recreate the field with the same key to restore access. ## Next steps - [Team Management](/docs/operations/team-management) -- Manage team access and permissions - [Notifications](/docs/operations/notifications) -- Configure notification preferences - [Events](/docs/operations/events) -- Monitor activity across your account --- # Team Management Source: https://docs.revkeen.com/docs/operations/team-management Invite team members, assign roles, and manage permissions RevKeen allows you to invite team members to your organization and assign them roles that control their access to different features. This guide explains the available roles, how to manage your team, and security best practices. ## Team roles RevKeen uses a role-based access model to manage permissions within your organization: | Role | Description | Typical Use | |------|-------------|-------------| | **Owner** | Full control over the organization including billing, settings, and team management | Business owner, primary account holder | | **Admin** | Full administrative access to manage settings, invite members, and configure integrations | Team leads, operations managers | | **Manager** | Day-to-day operations access | Manage customers, invoices, subscriptions | | **Support** | Customer support role | View and assist customers, issue refunds | | **Member** | Standard access to view and work with customers, subscriptions, and invoices | Sales staff, accountants | | **Viewer** | Read-only access | View dashboards and reports only | ## Role permissions Each role has different levels of access to RevKeen features. ### Owner - Full access to all features - Manage billing and subscription plans - Delete the organization - Transfer ownership to another member - Manage all team members including other owners ### Admin - Invite new team members - Remove members (except owners) - Configure payment gateways - Manage API keys and webhooks - Access all customer and billing data - Cannot manage billing or delete organization ### Manager - Manage customers, invoices, and subscriptions - View financial data - Cannot invite or manage team members - Cannot access API keys or settings ### Support - View and assist customers - Process refunds - Cannot manage products or view financial data - Cannot access settings ### Member - View and manage customers - Create and manage subscriptions - Create and send invoices - View payment history and reports - Cannot invite or manage team members - Cannot access API keys or settings ### Viewer - View dashboards and reports only - Cannot modify any data ### Permission matrix | Permission | Owner | Admin | Manager | Support | Viewer | |------------|:-----:|:-----:|:-------:|:-------:|:------:| | View dashboard | Yes | Yes | Yes | Yes | Yes | | Manage products | Yes | Yes | Yes | -- | -- | | Manage customers | Yes | Yes | Yes | Yes | -- | | Process refunds | Yes | Yes | Yes | Yes | -- | | View financial data | Yes | Yes | Yes | -- | Yes | | Manage team | Yes | Yes | -- | -- | -- | | Account settings | Yes | Yes | -- | -- | -- | | API keys | Yes | Yes | -- | -- | -- | > **Note:** Every organization must have at least one owner. You cannot remove or demote the last owner without first assigning ownership to another member. ## Team member list Navigate to **Settings > Team Members** to view all team members. The list displays: | Column | Description | |--------|-------------| | **Name** | Team member's name | | **Email** | Login email address | | **Role** | Assigned role (Owner, Admin, Manager, etc.) | | **Status** | Active, pending invite, or suspended | | **Last Active** | Last login date | ## Inviting team members Owners and admins can invite new team members: 1. Navigate to **Settings > Team Members** 2. Click **Invite Member** 3. Enter the invitee's email address 4. Select a role (Admin, Manager, Member, etc.) 5. Optionally add a personal message 6. Click **Send Invite** The invitee receives an email with a link to create their account and join your team. > **Note:** Pending invites expire after 7 days. You can resend the invitation from the Team Members page. > **Note:** If an invitation email does not arrive, check the spam folder. You can also resend invitations from the Team Members page. ## Managing existing members From the Team Members page, you can: - **Change roles** -- Promote or demote members between roles - **Remove members** -- Revoke access for team members who no longer need it - **Resend invitations** -- Send another email for pending invitations - **Revoke invitations** -- Cancel pending invitations before they are accepted ### Changing roles 1. Find the team member in the list 2. Click the actions menu 3. Select **Change Role** 4. Choose the new role 5. Click **Update** > **Note:** Changing a member's role takes effect immediately. They may lose access to certain features. ### Removing team members 1. Find the team member in the list 2. Click the actions menu 3. Select **Remove** 4. Confirm the removal Removed members immediately lose access but their activity history is preserved. > **Note:** Removing a member is immediate and permanent. The member will lose access to all organization data instantly. They can be re-invited later if needed. ### Suspending members Temporarily disable access without removing a member: 1. Find the team member 2. Click **Suspend** 3. They cannot log in until reactivated 4. Reactivate anytime to restore access ## Best practices - **Use the principle of least privilege** -- Assign the minimum role needed for each team member's responsibilities - **Have multiple owners for business continuity** -- Ensure at least two people have owner access in case of emergencies - **Review team access regularly** -- Periodically audit your team members and remove access for those who no longer need it - **Use work email addresses** -- Invite team members using their company email for better security and tracking - **Remove access immediately when employees leave** -- Do not leave stale accounts active - **Enable two-factor authentication for all users** -- Add an extra layer of security - **Use unique email addresses** -- No shared accounts ## Next steps - [Settings](/docs/operations/settings) -- Configure your account preferences - [Notifications](/docs/operations/notifications) -- Set up notification preferences for your team --- # Integrations Source: https://docs.revkeen.com/docs/integrations Connect RevKeen with your existing tools and workflows RevKeen integrates with popular accounting platforms, practice management systems, and business tools to streamline your payment workflows. Connect your existing stack and let data flow automatically between systems. ## Available Integrations | Integration | What it does | Setup effort | Status | Plan | |---|---|---|---|---| | [Customer Intelligence](/docs/integrations/customer-intelligence) | AI-powered payment failure, churn prediction, and health narratives | Low | Available | Pro+ | | [Payment Gateways](/docs/integrations/gateways) | NMI, Elavon, and gateway configuration | Medium | Available | All | | [PracticeHub](/docs/integrations/practicehub) | Sync patients, invoices, packages, and push payments back | Medium | Available | Pro (or Standard add-on) | | [Slack](/docs/integrations/slack) | Real-time payment and subscription notifications in channels | Low | Available | Pro+ | | [Xero](/docs/integrations/xero) | Sync invoices and payments with Xero accounting | Low | Available | Pro+ | | [QuickBooks](/docs/integrations/quickbooks) | Sync financial data with QuickBooks | Low | Available | Pro+ | | [Zapier](/docs/integrations/zapier) | Connect RevKeen to 5000+ apps via automation | Low | Coming Soon | Pro+ | | [Quaderno](/docs/integrations/quaderno) | Automate VAT/tax compliance, calculation, and reporting | Low | Available | Pro+ | | [Communication Channels](/docs/integrations/communication) | Email (all plans), SMS (all plans), WhatsApp (Pro+), Messenger (Pro+) | Low | Available | Varies | | [Custom Webhooks](/docs/integrations/webhooks) | Build any integration with real-time event notifications | Medium | Available | All | | [WooCommerce](/docs/integrations/woocommerce) | Accept payments through your WooCommerce store | Low | Coming Soon | Unlimited | | [Wodify](/docs/integrations/wodify) | Sync gym memberships and customer data | Medium | Coming Soon | -- | ## How Integrations Work RevKeen integrations use a secure, multi-tenant architecture: 1. **Credential Storage** -- API keys are stored securely in Infisical (not in your database). Credentials are encrypted at rest and never exposed to the browser. 2. **Isolated Workers** -- Each integration runs in its own isolated environment. One merchant's integration cannot access another merchant's data or credentials. 3. **Real-time Sync** -- Data syncs automatically based on your configuration. Most integrations use incremental sync, fetching only records that have changed since the last sync. 4. **PHI Compliance** -- Medical and clinical data is never synced. Only billing-safe fields like names, email addresses, invoice amounts, and due dates flow between systems. ## Marketplace Model Integration availability depends on your plan: - **Included** -- No extra cost with your plan - **Add-on** -- Fixed monthly fee on top of your plan - **Blocked** -- Upgrade your plan to unlock See [product facts](/docs/product-facts) for the full integration availability matrix by plan. ## Getting Started 1. Navigate to **Settings > Integrations** in your RevKeen dashboard 2. Click **Connect** on the integration you want to enable 3. Enter your API credentials for the external service 4. Configure sync settings based on your preferences 5. Start syncing -- data will flow automatically between systems > **Note:** Need help setting up an integration? Contact [support@revkeen.com](mailto:support@revkeen.com). --- # Communication Channels Source: https://docs.revkeen.com/docs/integrations/communication Configure email, WhatsApp, SMS, and Messenger notifications for customers ## Overview RevKeen's communication channels let you reach customers through the channels they prefer -- email, WhatsApp, SMS, or Messenger. Whether you are sending an invoice, a payment reminder, a receipt, or a dunning notification, you can configure which channels to use and customize the content for each. Communication channels are built on top of RevKeen's notification engine, which handles delivery, tracking, and retry logic automatically. ### Channel Availability by Plan | Channel | Standard | Pro | Unlimited | |---|:---:|:---:|:---:| | **Email** | Yes | Yes | Yes | | **SMS** | £0.05/SMS | 100/month included, then £0.04 | Unlimited | | **WhatsApp** | -- | Yes | Yes | | **Messenger** | -- | Yes | Yes | ## Email (All Plans) Email is RevKeen's primary communication channel and is available to all merchants. RevKeen sends transactional emails on your behalf for key billing events. ### What Gets Sent | Email Type | When It Sends | Customizable | |---|---|---| | Invoice email | When you send an invoice to a customer | Yes | | Payment receipt | After a successful payment | Yes | | Payment failed | After a failed payment attempt | Yes | | Subscription confirmation | When a subscription starts | Yes | | Subscription renewal | Before or after a renewal is processed | Yes | | Dunning reminder | During failed payment recovery | Yes | | Payment link | When you share a payment link via email | Yes | ### Configuration To configure email settings: 1. Navigate to **Settings > Email** in your RevKeen dashboard 2. Customize your email templates with your branding 3. Set your sender name and reply-to address 4. Configure which email types to send automatically 5. Preview and test each template before going live ### Branding You can customize the look and feel of all outgoing emails: - **Logo** -- Your company logo appears in the email header - **Colors** -- Match your brand's primary and accent colors - **Footer** -- Add your company address, support links, and social media - **Sender name** -- Emails come from your business name, not RevKeen ## SMS (All Plans) SMS notifications provide a direct channel for time-sensitive billing communications. Available on all plans with pricing that varies by tier: - **Standard:** £0.05 per SMS - **Pro:** 100 SMS per month included, then £0.04 per SMS - **Unlimited:** Unlimited SMS included ### Features - **Payment reminders** -- Short SMS reminders with a link to pay - **Payment confirmations** -- Instant confirmation after payment - **Subscription alerts** -- Upcoming renewal or expiration notices - **Two-factor payment verification** -- Optional SMS verification for high-value transactions ### Configuration SMS sending is handled through RevKeen's notification infrastructure. Configure SMS notifications in **Settings > Notifications** in your dashboard. ## WhatsApp (Pro and Unlimited) WhatsApp Business integration allows you to send billing notifications through WhatsApp, which has higher open rates than email in many markets. Available on Pro and Unlimited plans. ### Features - **Invoice delivery** -- Send invoices as WhatsApp messages with a payment link - **Payment reminders** -- Automated reminders for overdue invoices - **Payment confirmations** -- Instant receipt after successful payment - **Two-way messaging** -- Customers can reply with questions (routed to your support team) ### Requirements - A WhatsApp Business account - A verified business phone number - WhatsApp Business API access (RevKeen will help you set this up) ## Messenger via Twilio (Pro and Unlimited) Facebook Messenger integration allows you to send billing notifications through Messenger, reaching customers on a platform they use daily. Available on Pro and Unlimited plans. Powered by Twilio. ### Features - **Invoice delivery** -- Send invoices as Messenger messages with a payment link - **Payment reminders** -- Automated reminders for overdue invoices - **Payment confirmations** -- Instant receipt after successful payment - **Two-way messaging** -- Customers can reply with questions (routed to your support team) ### Requirements - A Facebook Business page - Twilio account with Messenger channel enabled - RevKeen will help you connect the channel during setup ## Channel Strategy Different channels work better for different situations: | Scenario | Recommended Channel | |---|---| | Initial invoice delivery | Email | | First payment reminder | Email | | Urgent overdue reminder | SMS, WhatsApp, or Messenger | | Payment receipt | Email | | Subscription renewal notice | Email | | Failed payment follow-up | SMS, WhatsApp, or Messenger | ## Multi-Channel Configuration You can configure a delivery sequence when multiple channels are available: 1. **Primary channel** -- The first channel attempted (usually email) 2. **Fallback channel** -- Used if the primary channel fails or goes unread after a configurable period 3. **Escalation channel** -- Used for urgent communications like final dunning attempts This ensures important billing communications reach customers even if they don't check one particular channel. --- # Customer Intelligence Source: https://docs.revkeen.com/docs/integrations/customer-intelligence AI-powered payment failure predictions, churn risk, and health narratives Customer Intelligence brings AI-powered predictions directly into RevKeen. Every customer is automatically analysed for payment failure risk, churn probability, and overall health -- with plain-language explanations and actionable recommendations. ## What You Get - **AI health narratives** -- A natural-language summary of each customer's payment behaviour, generated daily - **Payment failure predictions** -- A probability score for each customer's next payment failing, based on a 20-feature analysis - **Churn predictions** -- Monthly assessment of which customers are likely to leave, with contributing signals - **Unified Intelligence Panel** -- All predictions consolidated on the customer detail page - **Dashboard summary card** -- Aggregate risk metrics across your entire customer base ## Setting Up Customer Intelligence is a built-in RevKeen feature. No API keys, credentials, or external accounts are needed. 1. Go to **Apps > Customer Intelligence** in your RevKeen dashboard 2. Click **Activate** 3. Predictions will begin on the next scheduled run (see schedule below) > **Note:** Customer Intelligence requires at least one customer with invoice history. Predictions improve in accuracy as more payment data is collected. ## How Predictions Work Each prediction type follows the same pipeline: 1. **Feature extraction** -- RevKeen collects relevant signals from the customer's payment history, subscription status, and health score 2. **AI analysis** -- The feature vector is processed by a specialised AI model that returns a probability score, risk level, and explanatory factors 3. **Structured output** -- Results are stored with the customer record and surfaced in the dashboard ### Payment Failure Predictions The payment failure model analyses 20 features per customer, including: | Feature Category | Examples | |---|---| | Payment history | Recent failure rate, hard-decline count, average days to pay | | Method health | Card expiration proximity, method age, number of methods on file | | Billing patterns | Transaction amount volatility, frequency consistency, dunning depth | | Account signals | Tenure, subscription tier, recent plan changes | Each prediction produces: - **Failure probability** (0--100%) - **Risk level** (low, medium, or high) - **Top risk factors** with relative importance - **Recommended action** (e.g. "Update payment method", "Switch to manual invoicing") ### Churn Predictions The churn model runs monthly and evaluates: | Signal Category | Examples | |---|---| | Health trend | Score velocity, direction (improving/stable/declining) | | Subscription signals | Downgrades, cancellation requests, pause history | | Payment behaviour | Failure frequency over 90 days, recovery rate | | Engagement | Portal login frequency, support ticket volume | Each prediction produces: - **Churn probability** (0--100%) - **Risk level** (low, medium, or high) - **Risk signals** ordered by importance - **Recommended action** (e.g. "Schedule retention call", "Offer discount on renewal") ### AI Health Narratives After health scores are recalculated, an AI model generates a plain-language narrative for each customer explaining: - Current score and what it means - Recent changes and their causes - Specific risks or positive trends - Suggested next steps Narratives can be regenerated on demand from the customer detail page. ## Prediction Schedule | Prediction | Schedule | Scope | |---|---|---| | Health narratives | Daily at 03:30 UTC | All customers with health scores | | Payment failure | Daily at 04:00 UTC | All customers with active payment methods | | Churn | Monthly at 05:00 UTC (1st) | All customers with 30+ days of history | You can also trigger any prediction on demand from the customer detail page. ## Risk Levels | Level | Probability Range | Meaning | |---|---|---| | Low | 0--30% | No action needed | | Medium | 31--60% | Monitor and consider proactive outreach | | High | 61--100% | Immediate attention recommended | ## Outcome Tracking RevKeen records actual outcomes (did the payment fail? did the customer churn?) alongside predictions. This data is used to continuously measure model accuracy and improve future predictions. ## Where to View Predictions | Location | What's Shown | |---|---| | **Dashboard home** | Intelligence Summary card with aggregate metrics | | **Customer list** | Risk indicators alongside health scores | | **Customer detail** | Full Intelligence Panel with narrative, payment risk, and churn risk | | **Apps > Customer Intelligence** | Overall status, last run timestamps, and summary statistics | ## Troubleshooting | Issue | Solution | |---|---| | No predictions appearing | Predictions run on schedule -- check that at least one customer has invoice history | | Narrative says "No data" | The customer needs at least one completed invoice for narrative generation | | Risk level seems wrong | Predictions improve over time as more payment data accumulates | | Predictions not updating | Check the prediction schedule -- churn runs monthly, payment failure and narratives run daily | | Summary card shows zeros | New merchants will see data after the first scheduled prediction run | ## Deactivating To disable Customer Intelligence: 1. Go to **Apps > Customer Intelligence** 2. Click **Deactivate** Existing prediction data will be retained but no new predictions will be generated. --- # Payment Gateways Source: https://docs.revkeen.com/docs/integrations/gateways Supported payment processors - NMI, Elavon, and gateway configuration > **Note:** **Gateway Configuration** -- Payment gateway setup is typically handled during onboarding. Contact [support@revkeen.com](mailto:support@revkeen.com) if you need to change or add a gateway. ## Overview RevKeen uses a gateway-agnostic architecture to process payments. Rather than locking you into a single payment processor, RevKeen abstracts the gateway layer so you can connect to your preferred processor and switch between them without re-engineering your billing workflows. All transaction data, margin tracking, and reporting work identically regardless of which gateway is processing the payment. ## Supported Gateways ### NMI (Network Merchants Inc.) NMI is RevKeen's primary supported gateway. It provides a full-featured payment processing API with support for: - **Card-present and card-not-present** transactions - **Recurring billing** and tokenized payment storage (Customer Vault) - **ACH / eCheck** payments - **Refunds, voids, and partial refunds** - **Level 2 and Level 3** processing data for B2B transactions - **3D Secure** authentication NMI connects to multiple acquiring banks, giving you flexibility in choosing your merchant account provider. Most RevKeen merchants use NMI with their existing or new merchant account. ### Elavon Elavon is RevKeen's payment processing partner and one of the world's largest payment processors, owned by US Bancorp. RevKeen's payment processing is powered by Elavon, providing: - Direct acquiring relationships (no intermediary) - Support for Visa, Mastercard, American Express, Discover, and international card brands - Multi-currency processing - PCI-compliant hosted payment fields - Card-present support via PAX terminals ## Gateway-Agnostic Architecture RevKeen's billing engine treats gateways as interchangeable connectors. This means: - **Unified transaction model** -- Whether a payment is processed through NMI, Elavon, or a future gateway, it is stored in the same transaction table with the same data structure. Your dashboard, reports, and analytics work the same way regardless of processor. - **Gateway-specific adapters** -- Each gateway has its own adapter that translates RevKeen's internal payment requests into the gateway's API format. This handles differences in API structure, authentication, and response codes transparently. - **Credential isolation** -- Gateway credentials are stored securely per merchant in encrypted vault storage (Infisical). Each merchant's credentials are isolated and never shared. - **Processing account mapping** -- Merchants can have multiple processing accounts (e.g., different merchant accounts for different currencies or business entities). RevKeen routes transactions to the correct processing account based on configuration. ## How to Configure Your Gateway ### During Onboarding When you sign up for RevKeen, your account manager will help you: 1. Choose a payment gateway (NMI is recommended for most merchants) 2. Set up your merchant account with the gateway or connect an existing one 3. Provide your gateway API credentials to RevKeen (Security Key for NMI) 4. Test a transaction to verify the connection 5. Go live ### Adding a Gateway If you need to add or change your gateway configuration: 1. Navigate to **Settings > Payment Processing** in your RevKeen dashboard 2. Click **Add Processing Account** 3. Select your gateway type 4. Enter your API credentials 5. Run a test transaction to validate the connection 6. Set the new account as active ### Required Credentials | Gateway | Required Credentials | |---|---| | NMI | Security Key (API key) | | Elavon | Merchant ID, User ID, SSL PIN | ## Transaction Flow Regardless of which gateway you use, every transaction follows the same flow: 1. **Checkout** -- Customer enters payment details on your RevKeen-hosted checkout page or payment link 2. **Tokenization** -- Card details are tokenized by the gateway (never stored by RevKeen) 3. **Authorization** -- RevKeen sends the payment request through the gateway adapter 4. **Capture** -- The gateway processes the transaction with the acquiring bank 5. **Recording** -- RevKeen records the transaction with full cost data (processing fees, interchange, etc.) 6. **Notification** -- Webhook events fire, dashboard updates, and any integrations are triggered ## Cost Tracking One of RevKeen's key differentiators is tracking the actual cost of each transaction. When a payment is processed: - **Processing fees** from your gateway are captured and recorded - **Interchange and assessment fees** are tracked (where available from the gateway) - **Net revenue** is calculated automatically - **Margin per transaction** is visible in your dashboard This gives you a true picture of what each payment costs, not just what you earned. ## Frequently Asked Questions **Can I use multiple gateways?** Yes. You can configure multiple processing accounts and route transactions based on currency, business entity, or other criteria. Contact support for multi-gateway configuration. **What happens if my gateway goes down?** RevKeen monitors gateway health. If a transaction fails due to a gateway outage, the error is logged and you will be notified. Automatic failover between gateways is on the roadmap. **Are card details stored by RevKeen?** No. Card details are tokenized by the payment gateway. RevKeen stores only the token and last four digits for reference. Full card numbers never touch RevKeen's servers. **Can I switch gateways without losing data?** Yes. Because of the gateway-agnostic architecture, all your transaction history, customer data, and subscriptions remain intact when you switch gateways. Only new transactions will route through the new gateway. --- # PracticeHub Source: https://docs.revkeen.com/docs/integrations/practicehub Sync patients, appointments, invoices, and packages with PracticeHub Connect your PracticeHub practice management system with RevKeen to automatically sync patient data, invoices, and payments. This integration enables seamless payment collection for healthcare providers, wellness clinics, and fitness studios. > **Note:** **Add-On App** -- PracticeHub integration is available as a premium add-on to your RevKeen subscription. Contact [sales@revkeen.com](mailto:sales@revkeen.com) for pricing. ## Overview The PracticeHub integration creates a bi-directional sync between your practice management system and RevKeen's payment platform: - **Inbound**: Patients, invoices, and packages sync from PracticeHub to RevKeen - **Outbound**: Completed payments push from RevKeen to PracticeHub This allows your patients to pay invoices online while keeping your PracticeHub records automatically updated. ## Features - **Patient Sync** -- Import patients from PracticeHub as RevKeen customers with email matching - **Invoice Sync** -- Sync unpaid invoices (sent, partial, overdue) for online payment collection - **Automatic Payment Push** -- Push completed payments back to PracticeHub with full transaction details - **Package Sync** -- Sync service packages as RevKeen products for upselling and subscriptions ## Prerequisites Before connecting PracticeHub, you will need: - A PracticeHub account with API access enabled - Your PracticeHub API Key - Your PracticeHub Base URL (e.g., `https://yourclinic.practicehub.io`) > **Note:** Contact PracticeHub support to enable API access for your account if you don't have an API key. ## Setup Instructions ### Step 1: Get Your API Credentials 1. Log in to your PracticeHub admin panel 2. Navigate to **Settings > API Access** 3. Generate or copy your **API Key** 4. Note your **Base URL** (the URL you use to access PracticeHub) ### Step 2: Connect in RevKeen 1. Go to your RevKeen Dashboard 2. Navigate to **Settings > Integrations** 3. Find **PracticeHub** and click **Connect** 4. Enter your credentials: | Field | Description | Example | |---|---|---| | Base URL | Your PracticeHub instance URL | `https://yourclinic.practicehub.io` | | API Key | Your PracticeHub API key | `pk_live_xxxxx` | | App Name | Optional identifier | `RevKeen` | | Sync Enabled | Enable automatic syncing | `true` | 5. Click **Save & Validate** RevKeen will validate your credentials before saving. If validation fails, double-check your API key and Base URL. ### Step 3: Configure Sync Settings After connecting, you can configure what data syncs: - **Patients to Customers** -- Import patient records (email, name only -- no PHI) - **Invoices** -- Sync unpaid invoices for payment collection - **Packages to Products** -- Sync service packages as products - **Payment Methods** -- Map PracticeHub payment types to RevKeen ## Data Sync Details ### What Syncs | PracticeHub | RevKeen | Direction | Sync Trigger | |---|---|---|---| | Patients | Customers | PracticeHub to RevKeen | Updated timestamp | | Invoices (unpaid) | Invoices | PracticeHub to RevKeen | Updated timestamp | | Packages | Products | PracticeHub to RevKeen | Updated timestamp | | Payment Methods | Payment Method Mappings | PracticeHub to RevKeen | Initial sync | | -- | Payments | RevKeen to PracticeHub | Payment completion | ### Patient to Customer Mapping When a patient syncs from PracticeHub: | PracticeHub Field | RevKeen Field | Notes | |---|---|---| | `id` | `external_id` | Used for matching | | `email` | `email` | **Required** -- patients without email are skipped | | `first_name` | `first_name` | Direct mapping | | `last_name` | `last_name` | Direct mapping | | `phone` | `phone` | Direct mapping | | `patient_number` | `customer_number` | Used for display | ### What Does NOT Sync (PHI Compliance) > **Note:** RevKeen never syncs Protected Health Information (PHI) to maintain HIPAA compliance. The following fields are **blocked** and never imported: - Date of birth - Medical history - Diagnosis/symptoms - Treatment plans - Clinical notes - Staff notes - Appointment details (beyond basic scheduling) - Social Security numbers - Insurance information Only billing-safe fields are synced: - Email address - First name, Last name - Patient/customer number - Invoice amounts and due dates - Product/service names and prices ## How Payment Push Works When a customer pays an invoice through RevKeen, the payment is automatically recorded in PracticeHub. **Payment Flow:** 1. **Patient** pays invoice online via RevKeen 2. **RevKeen** processes card payment via the payment gateway 3. **Gateway** confirms payment 4. **RevKeen** POSTs payment to PracticeHub API 5. **PracticeHub** marks invoice as paid and updates balance ### What Gets Pushed When a payment is completed, RevKeen sends the following to PracticeHub: | Field | Description | Example | |---|---|---| | `amount` | Payment amount in cents | `5000` (= $50.00) | | `patient_id` | PracticeHub patient ID | `12345` | | `payment_type_id` | Mapped payment method | `7` (Card) | | `service` | Source system identifier | `revkeen` | | `service_id` | RevKeen transaction ID | `nmi_txn_abc123` | | `note` | Payment details | `Card - NMI Gateway \| Last4: 4242` | ## Sync Architecture ### Incremental Sync Strategy RevKeen tracks the last sync timestamp and only fetches records updated since then: ``` GET /api/patients?updated=gte:2024-11-30T10:00:00Z GET /api/invoices?updated=gte:2024-11-30T10:00:00Z&status=in:sent,partial,overdue GET /api/packages?updated=gte:2024-11-30T10:00:00Z ``` This ensures: - **Minimal API calls** -- Only changed records are fetched - **Fast sync** -- Updates complete in seconds, not minutes - **Respect rate limits** -- Won't overwhelm PracticeHub API ### Polling Schedule | Resource | Frequency | Notes | |---|---|---| | Patients | 1-30 seconds | More frequent when changes detected | | Invoices | 1-30 seconds | Focuses on unpaid invoices only | | Packages | 10-30 seconds | Less frequent (packages rarely change) | ## Payment Method Mapping RevKeen automatically maps payment methods between systems: | RevKeen Type | PracticeHub Match | |---|---| | `card` | "Card", "Credit Card", "Debit Card" | | `bank_transfer` | "Bank Transfer", "ACH", "EFT" | | `cash` | "Cash" | | `cheque` | "Cheque", "Check" | Payment method mappings are created automatically when you first sync. You can customize them in **Settings > Integrations > PracticeHub > Payment Methods**. ## Webhook Events RevKeen emits webhook events for PracticeHub sync activity: | Event | Description | |---|---| | `practicehub.customer.synced` | Customer created/updated from patient | | `practicehub.invoice.synced` | Invoice created/updated from PracticeHub | | `practicehub.payment.pushed` | Payment successfully pushed to PracticeHub | | `practicehub.payment.failed` | Payment push failed (will retry) | | `practicehub.sync.error` | Sync encountered an error | ## Error Handling and Retries RevKeen automatically handles common errors: | Error Type | Action | Max Retries | |---|---|---| | Rate limit (429) | Exponential backoff | 5 | | Server error (5xx) | Retry with delay | 3 | | Network timeout | Retry | 3 | | Authentication error (401) | Disable sync, notify admin | 0 | | Not found (404) | Skip record, log warning | 0 | If sync errors persist, check **Settings > Integrations > PracticeHub > Logs** for detailed error messages. ## Troubleshooting ### Connection Failed **Invalid API Key** - Verify your API key is correct (no extra spaces) - Check if the API key has expired - Ensure API access is enabled in PracticeHub **Invalid Base URL** - Use the full URL including `https://` - Don't include trailing slashes - Example: `https://yourclinic.practicehub.io` **Network Timeout** - Check if PracticeHub is accessible - Verify your firewall allows outbound connections - Try again in a few minutes ### Sync Issues **Patients Not Syncing** - Check if patients have email addresses (required) - Verify sync is enabled in settings - Check the Sync Status in your dashboard **Payments Not Pushing** - Verify the customer is linked to a PracticeHub patient - Check payment method mappings are configured - Review error logs in Settings > Integrations **Missing Invoices** - Only unpaid invoices sync to RevKeen - Paid invoices are skipped (already settled) - Check the invoice status in PracticeHub ## Frequently Asked Questions **How quickly do payments appear in PracticeHub?** Payments are pushed to PracticeHub within 1-5 seconds of being processed. The patient balance updates immediately once PracticeHub confirms receipt. **What happens if PracticeHub is down when a payment is made?** RevKeen queues the payment push and retries automatically. Payments are guaranteed to be delivered to PracticeHub once it's back online. You can see queued payments in your dashboard. **Can I sync specific patients only?** Currently, RevKeen syncs all active patients with email addresses. Contact support if you need filtering by patient groups or locations. **Do partial payments sync correctly?** Yes. When a patient makes a partial payment, RevKeen pushes the exact amount to PracticeHub. The invoice status updates to "partial" in both systems. **What about refunds?** Refunds processed in RevKeen are logged but not automatically pushed to PracticeHub. You will need to manually adjust the patient balance in PracticeHub for refunds. **Is my data secure?** Yes. All API communication uses HTTPS/TLS encryption. API keys are stored encrypted using industry-standard vault technology. RevKeen is working toward SOC 2 Type II certification. ## Support Need help with your PracticeHub integration? - **Email:** [support@revkeen.com](mailto:support@revkeen.com) - **Documentation:** [docs.revkeen.com](https://docs.revkeen.com) - **Status:** [status.revkeen.com](https://status.revkeen.com) - **Sales:** [sales@revkeen.com](mailto:sales@revkeen.com) (for pricing inquiries) --- # Quaderno Source: https://docs.revkeen.com/docs/integrations/quaderno Automate tax compliance with Quaderno tax calculation and reporting > **Note:** **Plan Availability** -- The Quaderno integration is available on Pro (450 VAT ops/month) and Unlimited plans. Not included on Standard. ## Overview The Quaderno integration connects RevKeen with Quaderno's tax automation platform to handle sales tax, VAT, and GST compliance across jurisdictions. Instead of manually calculating tax rates, generating compliant invoices, or tracking registration thresholds, Quaderno handles tax logic automatically for every transaction processed through RevKeen. This is the recommended approach for businesses selling internationally that need to stay compliant without adopting a Merchant of Record model. ## Features The integration automates the tax lifecycle from calculation through reporting: - **Automatic Tax Calculation** -- For every checkout, RevKeen calls Quaderno to determine the correct tax rate based on the customer's location, the product type, and the applicable tax jurisdiction. Supported tax types include EU VAT, UK VAT, US state and local sales tax, Canadian GST/HST/PST, Australian GST, and more. Tax is calculated in real time and displayed to the customer before payment. - **Tax-Compliant Invoices** -- When a payment completes, Quaderno generates a tax-compliant invoice or receipt that meets local requirements. This includes proper tax identification numbers, reverse charge notations for B2B EU transactions, and jurisdiction-specific formatting rules. These invoices are accessible from the RevKeen dashboard and can be sent to customers automatically. - **Threshold Monitoring** -- Quaderno tracks your sales volume by jurisdiction and alerts you when you are approaching or have crossed a tax registration threshold. This helps you stay ahead of compliance obligations in new markets rather than discovering them after the fact. - **Tax Reporting** -- Access consolidated tax reports showing how much tax you collected, in which jurisdictions, and for which periods. These reports simplify tax filing whether you handle it yourself or pass the data to your accountant. - **B2B Reverse Charge** -- For EU business-to-business transactions, the integration automatically applies reverse charge rules when the customer provides a valid VAT ID. The VAT ID is validated in real time during checkout. ## VAT Operations Pool RevKeen shares a global VAT API allowance across all tenants: - **Pro plan:** 450 VAT operations per month per tenant - **Unlimited plan:** Unlimited per-tenant (subject to global 1,000 ops/month pool) - **Standard plan:** Not included A VAT operation is allowed if: `tenantRemaining > 0 AND globalRemaining > 0` ## How It Works 1. Create a Quaderno account at [quaderno.io](https://quaderno.io) 2. Connect Quaderno from **Settings > Integrations** in RevKeen 3. Enter your Quaderno API key 4. Configure your business address and tax registration numbers 5. Map your products to Quaderno tax categories 6. Enable tax calculation on your checkout ## Why Use Quaderno with RevKeen RevKeen's Payment Service Provider model means you -- not a platform -- are the merchant of record. This gives you full control over your customer relationships and pricing, but it also means tax compliance is your responsibility. Quaderno bridges that gap: - **Stay compliant** -- Correct tax rates applied automatically based on customer location and product type - **No MoR lock-in** -- Get the tax compliance benefits of a Merchant of Record platform without surrendering your customer relationships or paying 4-5% platform fees - **Multi-jurisdiction** -- Sell globally with confidence that each transaction has the right tax treatment - **Audit ready** -- Every tax calculation is logged with the inputs and outputs for full traceability ## Related - [Tax](/docs/money/tax) -- How tax calculation works in RevKeen at checkout, invoicing, and reporting - [Product Facts](/docs/product-facts) -- VAT pool allocation across plans --- # QuickBooks Source: https://docs.revkeen.com/docs/integrations/quickbooks Sync financial data between RevKeen and QuickBooks > **Note:** **Plan Availability** -- The QuickBooks integration is available on Pro and Unlimited plans. Standard plan merchants can upgrade to unlock it. ## Overview The QuickBooks integration connects RevKeen with QuickBooks Online, automatically syncing invoices, payments, and customer data between your billing platform and your accounting system. Whether you use QuickBooks for bookkeeping, tax preparation, or financial reporting, this integration eliminates the need to manually re-enter billing transactions. ## Features The integration provides a comprehensive sync between RevKeen and QuickBooks Online: - **Invoice Sync** -- Invoices created in RevKeen push to QuickBooks as sales receipts or invoices. Line items, quantities, rates, and tax information transfer automatically so your QuickBooks records match your billing system exactly. - **Payment Recording** -- Payments collected through RevKeen record against the correct QuickBooks invoices. This includes full payments, partial payments, and refunds, keeping your accounts receivable ledger accurate without manual reconciliation. - **Customer Sync** -- RevKeen customers map to QuickBooks customer records. The integration matches by email address to prevent duplicates and creates new QuickBooks customers when a match is not found. - **Expense Tracking** -- Processing fees and platform costs captured by RevKeen can optionally sync to QuickBooks as expenses, giving you a complete picture of the cost of collecting payments. - **Sales Tax Mapping** -- Map RevKeen tax rates to QuickBooks tax codes for consistent tax reporting across both platforms. The integration respects your QuickBooks tax settings and jurisdiction configurations. ## How It Works 1. Connect your QuickBooks Online account from **Settings > Integrations** in RevKeen 2. Sign in to QuickBooks and authorize RevKeen via OAuth 3. Map RevKeen products to QuickBooks items or services 4. Configure account and tax code mappings 5. Choose a sync start date 6. Enable the integration ## Why Use RevKeen with QuickBooks QuickBooks handles general accounting and tax reporting. RevKeen handles billing intelligence and payment optimization. The integration lets each system do what it does best: - **Eliminate data entry** -- No more manually copying invoice data from RevKeen to QuickBooks - **Accurate books** -- Payments reconcile in real time instead of during monthly close - **Complete cost picture** -- Processing fees flow into QuickBooks automatically for true profit and loss reporting - **Tax season ready** -- Your QuickBooks data stays current with every transaction, reducing year-end scramble ## Setup Instructions ### Step 1: Connect Your QuickBooks Account 1. Go to **Settings > Integrations** in your RevKeen dashboard 2. Find **QuickBooks** and click **Connect** 3. Sign in to your QuickBooks Online account 4. Authorize RevKeen to access your QuickBooks data 5. Select the company file if you have multiple ### Step 2: Map Items and Accounts Configure how RevKeen products map to QuickBooks: | RevKeen Source | QuickBooks Destination | Default | |---|---|---| | Products | Items/Services | Auto-create | | Subscription revenue | Income account | Sales of Product Income | | One-time payments | Income account | Sales of Product Income | | Processing fees | Expense account | Bank Charges | | Refunds | Income account (negative) | Sales of Product Income | ### Step 3: Configure Tax Codes Map RevKeen tax rates to QuickBooks tax codes: 1. Navigate to QuickBooks integration settings 2. Click **Tax Code Mappings** 3. Match each RevKeen tax rate to the corresponding QuickBooks tax code 4. Save mappings ### Step 4: Choose Sync Start Date Select a sync start date to avoid duplicating data already in QuickBooks. ## What Syncs | RevKeen | QuickBooks | Direction | Trigger | |---|---|---|---| | Invoices | Invoices or Sales Receipts | RevKeen to QuickBooks | Invoice created/updated | | Payments | Invoice payments | RevKeen to QuickBooks | Payment completed | | Customers | Customers | RevKeen to QuickBooks | Customer created/updated | | Refunds | Credit memos or refund receipts | RevKeen to QuickBooks | Refund processed | | Processing fees | Expense entries | RevKeen to QuickBooks | Settlement completed | ## Sync Behavior - **Customer matching** by email address to prevent duplicates - **Invoice sync** within 60 seconds of creation in RevKeen - **Payment recording** against the matching QuickBooks invoice - **Duplicate prevention** using RevKeen invoice ID as reference number - **Multi-currency** transactions sync in the original currency ## Troubleshooting ### Connection Issues **OAuth token expired** - QuickBooks tokens expire after 100 days. Reconnect from **Settings > Integrations > QuickBooks** **Company file not found** - Ensure you selected the correct company during authorization - Disconnect and reconnect if needed ### Sync Issues **Invoice not appearing** - Check sync logs in **Settings > Integrations > QuickBooks > Logs** - Verify the invoice date is after your configured sync start date - Ensure the QuickBooks connection shows a green status **Customer duplicates** - QuickBooks matches by email. Ensure customer emails are consistent between systems - Merge duplicate QuickBooks customers manually if needed **Tax code errors** - Verify all RevKeen tax rates have a corresponding QuickBooks tax code mapping - Check that QuickBooks tax settings are enabled for your region ## Related - [Xero](/docs/integrations/xero) -- Alternative accounting integration - [Tax](/docs/money/tax) -- Tax calculation and reporting - [Invoices](/docs/using-revkeen/invoices-and-orders) -- Invoice management --- # Slack Source: https://docs.revkeen.com/docs/integrations/slack Get real-time payment and subscription notifications in Slack The Slack integration sends real-time notifications about payments, subscriptions, and other events directly to your Slack channels. Keep your team informed without leaving Slack. ## What You Get The Slack integration provides: - **Real-time notifications** -- Instant alerts for payment and subscription events - **Rich formatting** -- Detailed message cards with amounts, customer names, and product info - **Quick links** -- Direct links back to the RevKeen dashboard for every notification - **Customizable alerts** -- Choose which events to receive and which to ignore - **Multiple channels** -- Route different event types to different Slack channels ## Setting Up the Integration 1. Go to **Apps > Slack** in your RevKeen dashboard 2. Click **Connect to Slack** 3. Authorize RevKeen to access your Slack workspace 4. Select a default channel for notifications 5. Choose which events to receive 6. Save your settings > **Note:** You will need to be a Slack workspace admin or have permission to add apps. ## Available Notifications | Event | Description | |---|---| | **New payment** | Successful payment received | | **Failed payment** | Payment attempt failed | | **New subscription** | Customer started a subscription | | **Subscription cancelled** | Customer cancelled their subscription | | **New customer** | New customer created | | **Chargeback opened** | Dispute filed against a transaction | | **Large payment** | Payment above your configured threshold | | **Daily summary** | End-of-day revenue summary | ## Notification Format Notifications include: - Event type and icon - Customer name and email - Amount (for payment events) - Product or plan name - Link to view in RevKeen Example notification: ``` New Payment Received -------------------- Customer: John Doe (john@example.com) Amount: $99.00 Product: Pro Plan (Monthly) -------------------- View in RevKeen -> ``` ## Channel Routing Route different events to different channels to keep your team organized: | Channel | Suggested Events | |---|---| | **#sales** | New payments, new subscriptions | | **#support** | Failed payments, cancellations | | **#finance** | Chargebacks, large payments | | **#leadership** | Daily summaries | ## Thresholds and Filters Reduce noise by setting thresholds: - **Payment minimum** -- Only notify for payments above a certain amount - **Quiet hours** -- Batch notifications during off-hours instead of sending immediately - **Product filter** -- Only receive notifications for specific products ## Troubleshooting | Issue | Solution | |---|---| | Not receiving notifications | Check channel permissions and event selection | | Can't connect | Ensure you have Slack admin permissions | | Wrong channel | Update channel in RevKeen integration settings | | Too many notifications | Reduce selected events or set payment thresholds | ## Disconnecting Slack To remove the integration: 1. Go to **Apps > Slack** 2. Click **Disconnect** 3. Confirm the disconnection This will stop all Slack notifications from RevKeen. Your historical notification data in Slack channels will remain. --- # Custom Webhooks Source: https://docs.revkeen.com/docs/integrations/webhooks Build custom integrations with RevKeen webhook events For full webhook documentation -- including event catalog, signature verification, retry policy, and code examples -- see the canonical **[Webhooks](/docs/webhooks)** page. ## Quick Links - **Webhook Setup & Signature Verification** (/docs/webhooks): Register endpoints, verify signatures, and handle retries. - **Webhook Event Reference** (/docs/api-reference#tag/Webhooks): Full list of customer, invoice, subscription, payment, terminal, and usage events. - **Terminal API Overview** (/docs/developers/terminal-api/overview): Terminal-specific integration guidance and links to terminal event references. --- # Wodify Source: https://docs.revkeen.com/docs/integrations/wodify Sync gym membership data between RevKeen and Wodify > **Note:** **Coming Soon** -- The Wodify integration is currently in development. Contact [sales@revkeen.com](mailto:sales@revkeen.com) to be notified when it launches. ## What is Wodify? Wodify is a comprehensive gym management platform popular with CrossFit boxes, functional fitness studios, and gyms. It handles: - Class scheduling and reservations - Athlete performance tracking - Membership management - Retail and point of sale ## Planned Features The RevKeen + Wodify integration will provide: | Feature | Description | |---|---| | **Automatic membership sync** | Memberships created in RevKeen sync to Wodify | | **Payment processing** | Use RevKeen's checkout for Wodify memberships | | **Status synchronization** | Cancelled or paused subscriptions update in Wodify | | **Customer sync** | Customer data flows between systems | ## How It Will Work 1. Go to **Apps > Wodify** in RevKeen 2. Click **Connect to Wodify** 3. Enter your Wodify API credentials 4. Map your RevKeen products to Wodify memberships 5. Configure sync settings 6. Enable the integration > **Note:** You will need Wodify API access. Contact Wodify support if you don't have API credentials. ## Product Mapping Map RevKeen products to Wodify membership types: 1. In the Wodify integration settings 2. Click **Map Products** 3. For each RevKeen product, select the corresponding Wodify membership 4. Configure any additional mapping options 5. Save mappings ## Synchronization ### New Subscriptions 1. Customer completes checkout in RevKeen 2. Subscription is created in RevKeen 3. RevKeen sends data to Wodify 4. Member is created or updated in Wodify with active membership ### Subscription Changes Changes will sync automatically: | RevKeen Event | Wodify Action | |---|---| | Subscription created | Membership activated | | Subscription renewed | Membership extended | | Subscription paused | Membership paused (if supported) | | Subscription cancelled | Membership deactivated | | Plan changed | Membership type updated | ## Get Notified To be notified when the Wodify integration launches, contact [sales@revkeen.com](mailto:sales@revkeen.com) or speak with your account manager. --- # WooCommerce Source: https://docs.revkeen.com/docs/integrations/woocommerce Accept payments through your WooCommerce store with RevKeen > **Note:** **Coming Soon** -- The WooCommerce integration is currently in development. Join the waitlist by contacting [sales@revkeen.com](mailto:sales@revkeen.com) to be notified when it launches. ## Overview The WooCommerce integration will connect your WooCommerce-powered online store directly with RevKeen, enabling you to accept payments through RevKeen's checkout while keeping your product catalog and order data synchronized between both platforms. If you already use WooCommerce for e-commerce and want to leverage RevKeen's billing intelligence, margin tracking, and unified payment dashboard, this integration will bridge the gap. ## Planned Features The WooCommerce integration is designed to provide a seamless connection between your store and RevKeen: - **Payment Gateway Plugin** -- A WooCommerce payment gateway plugin that routes checkout payments through RevKeen. Customers complete their purchase on your WooCommerce storefront and pay via RevKeen's secure checkout, giving you access to margin tracking and cost analytics on every order. - **Order Synchronization** -- Orders placed in WooCommerce will automatically sync to RevKeen as invoices. Order status updates (fulfilled, refunded, cancelled) will flow bi-directionally so both systems stay in sync without manual data entry. - **Customer Data Sync** -- Customer profiles created during WooCommerce checkout will sync to RevKeen, giving you a unified view of all your customers whether they purchase through your online store or through direct invoicing. - **Product Catalog Mapping** -- Map WooCommerce products and variations to RevKeen products. This enables consistent reporting across sales channels and ensures that margin calculations account for all revenue sources. - **Subscription Support** -- For stores using WooCommerce Subscriptions, recurring billing will be managed through RevKeen's subscription engine with automatic renewal processing, dunning, and failed payment recovery. ## How It Will Work 1. Install the RevKeen payment gateway plugin from the WordPress plugin directory 2. Enter your RevKeen API key in the plugin settings 3. Configure which payment methods to offer at checkout 4. Map your WooCommerce products to RevKeen products (optional, for margin tracking) 5. Enable the gateway and start accepting payments ## Why Use RevKeen with WooCommerce WooCommerce gives you full control over your storefront and product catalog. RevKeen adds billing intelligence on top: - **Margin visibility** -- See the true profitability of every WooCommerce order after processing fees, refunds, and chargebacks - **Unified dashboard** -- View WooCommerce sales alongside direct invoices, subscriptions, and other revenue streams in one place - **Advanced dunning** -- Automatic failed payment recovery for subscription orders - **Multi-channel reporting** -- Compare performance across your WooCommerce store, payment links, and hosted checkout ## Get Notified To join the waitlist for the WooCommerce integration, contact [sales@revkeen.com](mailto:sales@revkeen.com) or speak with your account manager. --- # Xero Source: https://docs.revkeen.com/docs/integrations/xero Sync invoices and payments between RevKeen and Xero > **Note:** **Plan Availability** -- The Xero integration is available on Pro and Unlimited plans. Standard plan merchants can upgrade to unlock it. ## Overview The Xero integration syncs your RevKeen billing data with Xero's accounting platform, eliminating manual data entry between your payment system and your books. Invoices created in RevKeen appear in Xero automatically, and payments collected through RevKeen are reconciled against the correct Xero invoices in real time. ## Features The integration keeps your accounting records accurate and up to date without manual work: - **Invoice Sync** -- Invoices created in RevKeen automatically push to Xero as draft or approved invoices. Line items, tax rates, and customer details map directly to Xero's invoice format, so your books stay consistent with your billing system. - **Payment Reconciliation** -- When a customer pays an invoice through RevKeen, the corresponding Xero invoice is marked as paid automatically. Partial payments, refunds, and credit notes sync as well, keeping your accounts receivable accurate. - **Customer Mapping** -- RevKeen customers map to Xero contacts. New customers created in RevKeen automatically create corresponding contacts in Xero with matching names, email addresses, and billing addresses. - **Chart of Accounts Mapping** -- Configure which Xero accounts receive revenue from different RevKeen product lines. Map subscription revenue, one-time sales, and processing fees to the correct accounts for clean financial reporting. - **Multi-Currency Support** -- For businesses that bill in multiple currencies, the integration handles currency conversion and ensures Xero records match the original transaction currency. - **Fee Decomposition** -- RevKeen's margin tracking data flows into Xero, so processing fees and gateway costs appear as separate line items for accurate profit and loss reporting. ## How It Works 1. Connect your Xero organization from **Settings > Integrations** in RevKeen 2. Authorize RevKeen to access your Xero account via OAuth 3. Map your RevKeen products to Xero account codes 4. Configure tax rate mappings 5. Choose whether to sync historical data or start from a specific date 6. Enable the integration and invoices begin syncing automatically ## Why Use RevKeen with Xero Xero is excellent at accounting. RevKeen is excellent at billing intelligence. Together, they give you both: - **No double entry** -- Stop manually creating invoices in Xero that already exist in RevKeen - **Real-time reconciliation** -- Payments reconcile automatically instead of waiting for bank feeds - **Margin data in context** -- RevKeen's cost tracking complements Xero's profit and loss reporting - **Audit trail** -- Every sync event is logged, so you can trace any discrepancy between systems ## Setup Instructions ### Step 1: Connect Your Xero Account 1. Go to **Settings > Integrations** in your RevKeen dashboard 2. Find **Xero** and click **Connect** 3. You will be redirected to Xero to authorize RevKeen 4. Select the Xero organization you want to connect 5. Click **Allow Access** to complete the OAuth connection ### Step 2: Map Accounts After connecting, configure how RevKeen data maps to your Xero chart of accounts: | RevKeen Source | Xero Destination | Default | |---|---|---| | Subscription revenue | Revenue account | Sales | | One-time payments | Revenue account | Sales | | Processing fees | Expense account | Bank Fees | | Refunds | Contra-revenue account | Sales Returns | ### Step 3: Configure Tax Mappings Map RevKeen tax rates to Xero tax codes: 1. Navigate to the Xero integration settings 2. Click **Tax Mappings** 3. Match each RevKeen tax rate to the corresponding Xero tax code 4. Save mappings ### Step 4: Choose Sync Start Date Select whether to sync all historical data or start from a specific date. For existing Xero users, starting from the current date avoids duplicate entries. ## What Syncs | RevKeen | Xero | Direction | Trigger | |---|---|---|---| | Invoices | Invoices (Draft or Approved) | RevKeen to Xero | Invoice created/updated | | Payments | Invoice payments | RevKeen to Xero | Payment completed | | Customers | Contacts | RevKeen to Xero | Customer created/updated | | Refunds | Credit notes | RevKeen to Xero | Refund processed | | Processing fees | Expense transactions | RevKeen to Xero | Settlement completed | ## Sync Behavior - **New invoices** push to Xero within 60 seconds of creation - **Payments** reconcile against the matching Xero invoice automatically - **Partial payments** create partial payment records in Xero - **Refunds** create credit notes linked to the original invoice - **Duplicate prevention** uses the RevKeen invoice ID as an external reference in Xero ## Troubleshooting ### Connection Issues **OAuth token expired** - Xero tokens expire periodically. Go to **Settings > Integrations > Xero** and click **Reconnect** **Wrong organization selected** - Disconnect and reconnect, selecting the correct Xero organization ### Sync Issues **Invoice not appearing in Xero** - Check the sync log in **Settings > Integrations > Xero > Logs** - Verify the invoice was created after the sync start date - Ensure the Xero connection is active (green status indicator) **Payment not reconciling** - Confirm the customer exists as a contact in Xero - Check that account mappings are configured - Review error details in the sync log **Duplicate invoices** - This can happen if you imported historical data manually. Use the sync start date to avoid overlap ## Related - [QuickBooks](/docs/integrations/quickbooks) -- Alternative accounting integration - [Tax](/docs/money/tax) -- Tax calculation and reporting - [Invoices](/docs/using-revkeen/invoices-and-orders) -- Invoice management --- # Zapier Source: https://docs.revkeen.com/docs/integrations/zapier Connect RevKeen to thousands of apps with Zapier automation > **Note:** **Coming Soon** -- The Zapier integration is currently in development. It will be available on Pro and Unlimited plans. ## Overview The Zapier integration will connect RevKeen to over 5,000 apps without writing any code. Build automated workflows (called "Zaps") that trigger actions in other tools whenever something happens in RevKeen -- a payment is received, a subscription starts, an invoice goes overdue, or a customer is created. If you already use Zapier to connect your business tools, the RevKeen integration will slot directly into your existing automation stack. ## Planned Features The Zapier integration will expose RevKeen events as triggers and RevKeen actions as steps in Zapier workflows: - **Triggers (RevKeen to other apps)** -- Use RevKeen events to start Zapier workflows. Planned triggers include new payment received, subscription created, subscription cancelled, invoice overdue, customer created, refund issued, and chargeback opened. Each trigger will include the full event payload so you can use any field in your Zap. - **Actions (Other apps to RevKeen)** -- Use Zapier to push data into RevKeen. Planned actions include creating customers, creating invoices, sending payment links, and looking up transaction details. This will enable workflows like "when a deal closes in HubSpot, create a RevKeen invoice." - **Searches** -- Look up existing RevKeen data from within a Zap. Find a customer by email, look up an invoice by number, or retrieve a subscription's status to use in conditional logic. ## Example Automations Here are some workflows you will be able to build: - **New payment received** -- Add a row to a Google Sheet, send a thank-you email via Mailchimp, and create a task in Asana - **Subscription cancelled** -- Create a ticket in Zendesk, add the customer to a win-back campaign in ActiveCampaign, and notify your team in Slack - **Invoice overdue** -- Send a reminder via Twilio SMS, log in Airtable, and escalate in your project management tool - **New customer created** -- Add to your CRM (Salesforce, HubSpot, Pipedrive), subscribe to a mailing list, and send a welcome sequence ## Why Zapier with RevKeen Zapier will remove the need for custom development when connecting RevKeen to the rest of your business: - **No code required** -- Build integrations through a visual workflow builder - **5,000+ apps** -- Connect to CRMs, email tools, spreadsheets, project management, and more - **Conditional logic** -- Use filters and paths to route events based on amount, customer, product, or any other field - **Reliable delivery** -- Zapier retries failed steps and logs every execution for debugging --- # Fundamentals Source: https://docs.revkeen.com/docs/fundamentals Cross-cutting reference for the RevKeen API The fundamentals are the rules every RevKeen integration depends on — how requests are authenticated, how responses are paginated, how to retry safely, and how we version the API. Read these once; reach for them again when something is ambiguous. - **Idempotency** (/docs/fundamentals/idempotency): Retry mutations safely with an `Idempotency-Key`. - **Pagination** (/docs/fundamentals/pagination): Iterate over list responses with `limit` and `offset`. - **Versioning** (/docs/fundamentals/versioning): Pin the API version with the `RevKeen-Version` header. - **Errors** (/docs/errors): Error envelope, status codes, and retry guidance. --- # Better Auth Plugin Source: https://docs.revkeen.com/docs/fundamentals/better-auth Add RevKeen billing, checkout, and customer portal to your Better Auth app `@revkeen/better-auth` is a [Better Auth](https://better-auth.com) plugin that adds RevKeen billing capabilities to your app. It auto-creates RevKeen customers on signup, generates checkout sessions, exposes a customer billing portal, and verifies webhook signatures. ## Installation ```bash npm install @revkeen/better-auth @revkeen/sdk ``` ## Server setup ```typescript const rk = new RevKeenClient({ apiKey: process.env.REVKEEN_API_KEY! }); export const auth = betterAuth({ // ... your existing config plugins: [ revkeen({ client: rk, createCustomerOnSignUp: true, checkout: { successUrl: "/thank-you", cancelUrl: "/pricing", }, portal: true, webhooks: { secret: process.env.REVKEEN_WEBHOOK_SECRET!, onEvent: { "payment.succeeded": async (event) => { console.log("Payment succeeded:", event.data.object); }, "subscription.cancelled": async (event) => { console.log("Subscription cancelled:", event.data.object); }, }, }, }), ], }); ``` ## Client setup ```typescript export const authClient = createAuthClient({ plugins: [revkeenClient()], }); ``` ## Usage ### Create a checkout session ```typescript const { url } = await authClient.revkeen.checkout({ priceId: "price_xxx", }); // Redirect to checkout window.location.href = url; ``` ### Get customer billing portal data ```typescript const portal = await authClient.revkeen.portal(); console.log(portal.subscriptions); // Active subscriptions console.log(portal.invoices); // Recent invoices console.log(portal.paymentMethods); // Saved payment methods ``` ## How it works 1. **On signup** — the plugin creates a RevKeen customer via the SDK and stores the customer ID in user metadata 2. **Checkout** — `POST /api/auth/revkeen/checkout` creates a checkout session tied to the RevKeen customer 3. **Portal** — `GET /api/auth/revkeen/portal` returns the customer's subscriptions, invoices, and payment methods 4. **Webhooks** — `POST /api/auth/revkeen/webhooks` verifies the signature and dispatches to your handlers ## Configuration reference | Option | Type | Default | Description | |--------|------|---------|-------------| | `client` | `RevKeenClient` | required | Pre-configured SDK instance | | `createCustomerOnSignUp` | `boolean` | `true` | Auto-create RevKeen customer on signup | | `checkout.successUrl` | `string` | — | Default redirect after payment | | `checkout.cancelUrl` | `string` | — | Default redirect on cancel | | `portal` | `boolean` | `false` | Enable customer portal endpoint | | `webhooks.secret` | `string` | — | Webhook signing secret | | `webhooks.onEvent` | `Record` | — | Event handlers by type | ## Next Steps - **Authentication** (/docs/getting-started/authentication): API key and OAuth authentication reference. - **Webhooks** (/docs/webhooks): Webhook event types and delivery details. - **TypeScript SDK** (/docs/sdks/typescript): Full SDK reference for server-side integrations. --- # Idempotency Source: https://docs.revkeen.com/docs/fundamentals/idempotency Safely retry mutations using the Idempotency-Key header Send an `Idempotency-Key` on every mutation so RevKeen can safely replay a stored response when your request times out or your client retries. > **Note:** Every `POST`, `PATCH`, and `PUT` that moves money or creates a resource **must** set `Idempotency-Key`. Network retries without a key can produce duplicate charges, invoices, or refunds. ## The header ```http POST /v2/invoices HTTP/1.1 Host: api.revkeen.com x-api-key: rk_live_... Idempotency-Key: 3d4e1b2c-1f5a-4c9b-9e0e-5a1c8a5a2f7a Content-Type: application/json ``` | Rule | Detail | |-------------------------------|--------------------------------------------------------------------------------------| | Accepted methods | `POST`, `PATCH`, `PUT`. `GET` and `DELETE` do not honour the header. | | Recommended value | UUID v4 (36 chars). | | Accepted value | Any string, 1–255 chars, scoped per API key. | | Lifetime | 24 hours from first use. | | Expiry behaviour | After expiry the key is forgotten; reusing it starts a new mutation. | ## Replay semantics When RevKeen receives a request with an `Idempotency-Key` it has seen before in the last 24 hours: 1. **Same key + same body + same path** → return the **stored response** (status, body, headers). The underlying resource is **not** mutated again. 2. **Same key + different body** → `409 Conflict` with `error.code = "idempotency_conflict"`. The original stored response is not returned. 3. **Same key on a different endpoint** → treated as a new mutation; keys are scoped per method + path. The `Idempotency-Replayed: true` response header is set when you receive a stored response. ## Which errors are stored Only final responses are cached. In-flight state (for example a pending gateway call) is **not** cached, so an immediate retry during processing may return `409 idempotency_in_progress` — back off briefly and retry. | Scenario | Stored? | Retry behaviour | |--------------------------------------------|--------:|--------------------------------------------------------| | `2xx` success | Yes | Retry returns the stored success response. | | `4xx` validation / permission error | Yes | Retry returns the same `4xx`. | | `5xx` after the gateway call completed | Yes | Retry returns the stored `5xx`. | | `5xx` before the gateway call completed | No | Retry may re-attempt the gateway call. | | Network timeout (no response received) | No | Retry is safe — the key will either match or replay. | ## Interaction with SDK auto-retries All official SDKs automatically attach an `Idempotency-Key` to safe-to-retry requests and transparently retry `5xx`, `429`, and network errors up to 3 times. If you set `Idempotency-Key` yourself, the SDK uses your value. You only need to override this for cross-process retry scenarios (queue worker replays, durable workflows). ## Examples ```bash curl https://staging-api.revkeen.com/v2/refunds \ -H "x-api-key: $REVKEEN_API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "charge": "ch_01HT...", "amount": 1500 }' ``` ```ts const client = new RevKeen({ apiKey: process.env.REVKEEN_API_KEY! }); const refund = await client.refunds.create( { charge: "ch_01HT...", amount: 1500 }, { idempotencyKey: randomUUID() }, ); ``` ```go "github.com/google/uuid" revkeen "github.com/RevKeen/sdk-go" ) refund, err := client.Refunds.Create(ctx, &revkeen.RefundCreateParams{ Charge: revkeen.String("ch_01HT..."), Amount: revkeen.Int64(1500), }, revkeen.WithIdempotencyKey(uuid.NewString())) ``` ```php use RevKeen\RevKeenClient; use Ramsey\Uuid\Uuid; $client = new RevKeenClient(['api_key' => getenv('REVKEEN_API_KEY')]); $refund = $client->refunds->create( ['charge' => 'ch_01HT...', 'amount' => 1500], ['idempotency_key' => Uuid::uuid4()->toString()] ); ``` ## Best practices - **Generate one key per logical operation**, not per HTTP retry. A background job that charges a customer should use the same key across all in-process retries; the next scheduled run uses a fresh key. - **Persist the key alongside the record** you are creating (invoice, charge, refund). Reuse it if the job is re-run. - **Do not reuse keys across different request bodies** — that produces a `409 idempotency_conflict`. - **Expect `5xx` to be replayed on retry.** A stored error is not a reason to abandon; surface it to the operator so they can decide whether to retry with a new key. ## See also - **Errors** (/docs/errors): Handle `409 idempotency_conflict` and `409 idempotency_in_progress`. - **Versioning** (/docs/fundamentals/versioning): Pin the API version your integration is built against. - **API Reference** (/docs/api-reference): See which endpoints accept `Idempotency-Key`. --- # Pagination Source: https://docs.revkeen.com/docs/fundamentals/pagination Iterate over list responses using limit and offset All list endpoints in the RevKeen API use **offset-based pagination** via `limit` and `offset` query parameters. Responses are wrapped in a `data` array alongside a `pagination` block describing the current window. > **Note:** If you are migrating from a cursor-based API, think of `offset` as the zero-based index of the first item you want back and `limit` as the page size. ## Request parameters | Parameter | Type | Default | Max | Description | |-----------|-----------|--------:|----:|----------------------------------------------------------------------| | `limit` | `integer` | 25 | 100 | Number of items to return. Values above the max are clamped. | | `offset` | `integer` | 0 | — | Zero-based index of the first item to return. | List endpoints may also expose resource-specific filters (for example `status`, `search`, or `created_after`). See each endpoint's reference for the full parameter list. ## Response shape ```json { "data": [ { "id": "cus_01HT...", "name": "Acme Clinic", "email": "ops@acme.example" }, { "id": "cus_01HT...", "name": "Riverside Dental", "email": "admin@rsd.example" } ], "pagination": { "limit": 25, "offset": 0, "total": 312, "hasMore": true } } ``` | Field | Type | Description | |-----------------------|-----------|----------------------------------------------------------------------| | `data` | `array` | Current page of items. | | `pagination.limit` | `integer` | Echo of the requested `limit` after clamping. | | `pagination.offset` | `integer` | Echo of the requested `offset`. | | `pagination.total` | `integer` | Total items matching the filter, across all pages. | | `pagination.hasMore` | `boolean` | `true` when `offset + data.length < total`. | ## Iteration pattern Continue fetching until `pagination.hasMore` is `false`. Advance `offset` by the page size, not by `data.length` — the latter drifts on the last page. ```bash # Page 1 curl "https://staging-api.revkeen.com/v2/customers?limit=100&offset=0" \ -H "x-api-key: $REVKEEN_API_KEY" # Page 2 curl "https://staging-api.revkeen.com/v2/customers?limit=100&offset=100" \ -H "x-api-key: $REVKEEN_API_KEY" ``` ```ts const client = new RevKeen({ apiKey: process.env.REVKEEN_API_KEY! }); // Manual iteration for (let offset = 0; ; offset += 100) { const page = await client.customers.list({ limit: 100, offset }); for (const customer of page.data) { // … } if (!page.pagination.hasMore) break; } // SDK helper — automatic pagination for await (const customer of client.customers.listAutoPaging({ limit: 100 })) { // … } ``` ```go iter := client.Customers.List(ctx, &revkeen.CustomerListParams{Limit: 100}) for iter.Next() { customer := iter.Current() // … } if err := iter.Err(); err != nil { return err } ``` ```php use RevKeen\RevKeenClient; $client = new RevKeenClient(['api_key' => getenv('REVKEEN_API_KEY')]); foreach ($client->customers->autoPagingList(['limit' => 100]) as $customer) { // … } ``` ## Choosing a page size - **Default (`limit=25`)** is tuned for interactive UIs. - **`limit=100`** is the right choice for batch workloads and exports. - For end-user-facing lists, page from the server rather than fetching all pages and slicing client-side — latency and memory both scale linearly. ## Stability across pages Items are ordered by `createdAt DESC, id DESC` unless a list endpoint documents otherwise. If new items are created while you are iterating, an item may appear on a later page than expected. For strict one-shot snapshots, filter by a fixed `created_before` timestamp. ## See also - **Errors** (/docs/errors): Handle `400 invalid_request_error` for malformed `limit` or `offset`. - **Idempotency** (/docs/fundamentals/idempotency): Mutations are idempotent; reads are safe to repeat. - **API Reference** (/docs/api-reference): Per-endpoint parameter reference. --- # Versioning Source: https://docs.revkeen.com/docs/fundamentals/versioning Pin the RevKeen API version and understand our deprecation policy The RevKeen API is versioned by **release date**. Pin your integration to a specific version with the `RevKeen-Version` header so schema changes and new enum values never arrive silently. > **Note:** **Current version: `2026-05-01`**. New account-level defaults use this version; older integrations are honoured via the header until the deprecation window expires. ## Setting the version ```http GET /v2/customers HTTP/1.1 Host: api.revkeen.com x-api-key: rk_live_... RevKeen-Version: 2026-05-01 ``` - If you omit the header, requests use the **default version pinned to your API key** at the time it was issued. - The effective version is echoed back on every response as `RevKeen-Version`. - Override per-request by setting the header; override per-SDK-client by configuring `apiVersion` on the constructor. ```ts const client = new RevKeen({ apiKey: process.env.REVKEEN_API_KEY!, apiVersion: "2026-05-01", }); ``` ```go client := revkeen.NewClient(revkeen.Config{ APIKey: os.Getenv("REVKEEN_API_KEY"), APIVersion: "2026-05-01", }) ``` ```php use RevKeen\RevKeenClient; $client = new RevKeenClient([ 'api_key' => getenv('REVKEEN_API_KEY'), 'api_version' => '2026-05-01', ]); ``` ## What counts as a breaking change Any of the following ship **only** in a new version. They never change under an existing version header. - Removing or renaming a field - Changing a field's type, format, or nullability - Adding a required field to a request body - Removing an endpoint or HTTP method - Changing an HTTP status code for an existing response - Tightening a validation rule so previously-accepted inputs become invalid The following are **non-breaking** and can appear at any time under any version: - Adding new endpoints or HTTP methods - Adding optional request parameters - Adding new response fields - Adding new enum values (handle unknown values defensively) - Adding new webhook event types - Adding new error `code` values under an existing `error.type` > **Note:** Treat enum fields as open sets. Always have a default branch for unknown values, and serialise unknown fields rather than dropping them when you round-trip a resource. ## Deprecation policy - **Minimum supported window:** 12 months from the date a version is superseded. - **Deprecation notices** are sent via email to account admins 180 days before a version is retired. - **Sunset headers** are set on every response in the final 30 days: ```http Sunset: Wed, 01 Jul 2026 00:00:00 GMT Deprecation: version="2025-09-01" Link: ; rel="deprecation" ``` - **After sunset**, requests using the retired version receive `400 Bad Request` with `error.code = "api_version_retired"`. ## Upgrading between versions 1. **Read the [Changelog](/changelog)** for the new version. Breaking changes are flagged explicitly. 2. **Set the version header on a single request** in a staging environment and run your integration tests. 3. **Roll out by setting `apiVersion` on one SDK client** rather than flipping the account default — this limits blast radius. 4. **Promote the account default** via the dashboard once all services have shipped with the new header. ## SDK compatibility SDK minor versions correspond one-to-one with API versions. Upgrading an SDK patch version (for example `1.14.3 → 1.14.4`) never changes the API version it targets — only bug fixes and non-breaking additions. | SDK | Latest | Minimum API version | Current API version | |----------------------------------------------------------------------------|---------|---------------------|---------------------| | [TypeScript](https://github.com/RevKeen/sdk-typescript) | — | `2025-09-01` | `2026-05-01` | | [Go](https://github.com/RevKeen/sdk-go) | — | `2025-09-01` | `2026-05-01` | | [PHP](https://github.com/RevKeen/sdk-php) | — | `2025-09-01` | `2026-05-01` | Version numbers are updated on SDK release. Check the repositories for current tags. ## See also - **Changelog** (/changelog): Breaking and non-breaking changes by version. - **Errors** (/docs/errors): `api_version_retired` and other version-related error codes. - **SDKs** (/docs/sdks): Install and configure an official SDK. --- # Developers Source: https://docs.revkeen.com/docs/developers Build on RevKeen with the REST API, CLI, official SDKs, webhooks, terminal flows, and MCP tools # Build on RevKeen Use the RevKeen API, CLI, official SDKs, webhooks, terminal flows, and MCP tools to build billing, payments, subscriptions, terminal, and automation workflows. [API Reference](/docs/api-reference) · [Quickstart](/docs/getting-started/quickstart) · [SDKs](/docs/sdks) · [CLI](/docs/cli) · [MCP](/docs/mcp) ## Developer surfaces - **API Reference** (/docs/api-reference): Interactive REST and webhook reference powered by Fumadocs OpenAPI. - **Quickstart** (/docs/getting-started/quickstart): Go from staging key to first API call and first webhook delivery. - **SDKs** (/docs/sdks): Official TypeScript, Go, and PHP libraries generated from the canonical OpenAPI specification. - **CLI** (/docs/cli): Run common billing and operations workflows from your terminal. - **MCP** (/docs/mcp): Connect RevKeen tools to Claude, Cursor, VS Code, and other MCP-aware hosts. ## Choose the right surface | If you are building... | Start here | Why | |------------------------|------------|-----| | Application code | [SDKs](/docs/sdks) | Typed clients with retries, pagination, and webhook helpers | | Raw HTTP integrations | [API Reference](/docs/api-reference) | Canonical request and response contract | | Terminal workflows | [CLI](/docs/cli) | Fast operator tasks and interactive prompts | | AI agents | [MCP](/docs/mcp) | OAuth-scoped tools over remote MCP | ## Common build paths - **Accept payments** (/docs/api-reference#tag/Checkout-Sessions): Create checkout sessions and payment links for hosted payment flows. - **Manage subscriptions** (/docs/using-revkeen/subscriptions): Build recurring billing flows with products, prices, and subscription lifecycle events. - **Handle webhooks** (/docs/webhooks): Verify signatures, process retries safely, and keep consumers idempotent. - **Use the CLI** (/docs/cli): Manage customers, invoices, and billing from your terminal with the RevKeen CLI. - **Use the SDKs** (/docs/sdks): Start from the official TypeScript, Go, or PHP client instead of hand-rolling requests. - **Build terminal flows** (/docs/developers/terminal-api/overview): Run card-present device discovery, payment initiation, and terminal operations. - **Build with MCP** (/docs/mcp): Connect RevKeen tools to AI hosts over MCP as a separate integration surface. ## Core concepts - **Authentication** Use `x-api-key` on server-side REST requests. Use live keys in production and `rk_sandbox_*` keys in staging. [Read authentication](/docs/getting-started/authentication) - **Environments** RevKeen separates production, staging, and mock so you can choose the right level of safety and realism for each task. [Read environments](/docs/getting-started/environments) - **Idempotency** Add `Idempotency-Key` on write requests that must be safe to retry without creating duplicate financial state. [See the API reference](/docs/api-reference) - **Webhooks** RevKeen pushes billing and payment events to your systems. Consumers should verify signatures and deduplicate by event ID. [Read webhook guidance](/docs/webhooks) - **Errors and rate limits** Handle `4xx`, `5xx`, and `429` responses explicitly and log request IDs so you can trace issues quickly. [See the API reference](/docs/api-reference) ## Tools and downloads - **OpenAPI document** (/api/openapi-spec): Download the machine-readable contract used by fumadocs-openapi, SDK generation, and external tooling. - **API Reference** (/docs/api-reference): Browse the canonical REST and webhook reference generated from the committed OpenAPI contract. - **RevKeen CLI** (/docs/cli): Run operator workflows and resource actions from your terminal. - **TypeScript SDK** (/docs/sdks/typescript): Official Node.js and TypeScript client library. - **Go SDK** (/docs/sdks/go): Official Go client library for services and CLI tools. - **PHP SDK** (/docs/sdks/php): Official PHP client library for Laravel, Symfony, WordPress, and PHP apps. - **MCP guide** (/docs/mcp): Install and connect the RevKeen MCP server in supported AI hosts. ## Production checklist - [ ] Use staging first before sending any live traffic. - [ ] Verify webhook signatures before processing events. - [ ] Make webhook consumers idempotent and deduplicate by event ID. - [ ] Rotate live secrets and keep keys server-side only. - [ ] Monitor failures, retries, and rate-limit responses. --- # Terminal API Overview Source: https://docs.revkeen.com/docs/developers/terminal-api/overview Build card-present terminal flows on top of the RevKeen API The Terminal API lets you initiate card-present payments, discover devices, and process terminal operations through the same RevKeen platform used for online billing. > **Note:** Use this page for the terminal integration model. Use [API Reference](/docs/api-reference#tag/Terminal-Payments) for endpoint details, schemas, and request examples. ## What the terminal surface covers - **Device discovery** Find the correct `device_id` before initiating a payment. - **Payment lifecycle** Initiate sale, refund, and void flows and track the resulting terminal state. - **Async results** Use webhooks for approved, declined, cancelled, timed-out, and error outcomes. - **Operational safety** Handle per-device concurrency, stale heartbeats, retries, and idempotency carefully. ## Core flow 1. List terminal devices and choose an online, paired device. 2. Create a terminal payment against that `device_id`. 3. Wait for the result through webhooks or by polling the payment resource. 4. Reconcile the card-present result with the rest of your billing workflow. ## Environment model Use the same public API environments as the rest of RevKeen: | Environment | Base URL | Use when | |-------------|----------|----------| | **Staging** | `https://staging-api.revkeen.com/v2` | Integration development, QA, device workflow validation | | **Production** | `https://api.revkeen.com/v2` | Live terminal traffic | | **Mock** | `https://mock-api.revkeen.com/v2` | Response-shape validation only | ## Operating principles - Always check device status before creating a payment. - Use `Idempotency-Key` on terminal write operations. - Expect results asynchronously and prefer webhook-driven state updates. - Treat `device_busy`, offline devices, and timed-out flows as normal operating cases. ## Next Steps - **Terminal Payments Reference** (/docs/api-reference#tag/Terminal-Payments): Use the API reference for payment endpoints, request bodies, and response schemas. - **Terminal Devices Reference** (/docs/api-reference#tag/Terminal-Devices): Use the API reference for device discovery and device status details. - **Webhooks** (/docs/webhooks): Handle terminal delivery reliability the same way you handle the rest of RevKeen webhooks. --- # Official SDKs Source: https://docs.revkeen.com/docs/sdks Typed, versioned, and generated from the RevKeen OpenAPI contract RevKeen ships three official server-side SDKs. Every client is generated from [packages/openapi/openapi.json](https://github.com/salespie/salespie-payment-portal/blob/development/packages/openapi/openapi.json), so the REST reference, examples, and SDK methods stay aligned. ## Server-side SDKs - **TypeScript** (/docs/sdks/typescript): Node.js, Bun, Deno, Cloudflare Workers, Vercel Edge. `@revkeen/sdk` on [npm](https://www.npmjs.com/package/@revkeen/sdk) · [github.com/RevKeen/sdk-typescript](https://github.com/RevKeen/sdk-typescript) - **Go** (/docs/sdks/go): Idiomatic `context.Context` + typed structs. `github.com/RevKeen/sdk-go` · [pkg.go.dev](https://pkg.go.dev/github.com/RevKeen/sdk-go) - **PHP** (/docs/sdks/php): PHP 8.1+, PSR-4 autoloading, Laravel + Symfony adapters. `revkeen/sdk-php` on [Packagist](https://packagist.org/packages/revkeen/sdk-php) · [github.com/RevKeen/sdk-php](https://github.com/RevKeen/sdk-php) ## Choose by runtime | SDK | Best for | Install | Runtime | |-----|----------|---------|---------| | TypeScript | Node services, edge runtimes, full-stack apps | `npm install @revkeen/sdk` | Node.js 18+, Bun, Deno, Workers | | Go | Backend services, workers, internal tooling | `go get github.com/RevKeen/sdk-go` | Go 1.21+ | | PHP | Laravel, Symfony, WordPress, PHP applications | `composer require revkeen/sdk-php` | PHP 8.1+ | ## Shared client shape Every SDK exposes the same resource-oriented model — resource, method, typed params. | TypeScript | Go | PHP | |------------|----|-----| | `client.customers.create({...})` | `client.Customers.Create(ctx, params)` | `$client->customers->create([...])` | | `client.invoices.finalize(id)` | `client.Invoices.Finalize(ctx, id)` | `$client->invoices->finalize($id)` | | `client.webhooks.verify(...)` | `revkeen.Webhooks.Verify(...)` | `WebhookVerifier::verify(...)` | | `for await (…)` auto-paging | `iter.Next()` iterator | `foreach ($client->…->autoPagingList())` | ## What every SDK gives you - Typed request and response — compile-time safety, autocomplete, no `interface{}` / `any` / `stdClass` - Automatic retries on `5xx`, `429`, network errors with exponential backoff - Automatic idempotency keys on safe-to-retry mutations - Pagination helpers (`autoPagingList` / iterators) - Webhook signature verification in one line - OAuth 2.1 + API-key auth — both first-class - Structured errors with `code`, `status`, `request_id` ## Install quickly ```bash npm install @revkeen/sdk # or: pnpm add / yarn add / bun add ``` ```bash go get github.com/RevKeen/sdk-go ``` ```bash composer require revkeen/sdk-php ``` ## Versioning SDK minor versions map 1:1 to API versions. Patch versions carry bug fixes and non-breaking additions under the same API version. | SDK | Package | Compatibility docs | |-----|---------|--------------------| | [TypeScript](https://github.com/RevKeen/sdk-typescript) | `@revkeen/sdk` | [Versioning](/docs/fundamentals/versioning) | | [Go](https://github.com/RevKeen/sdk-go) | `github.com/RevKeen/sdk-go` | [Versioning](/docs/fundamentals/versioning) | | [PHP](https://github.com/RevKeen/sdk-php) | `revkeen/sdk-php` | [Versioning](/docs/fundamentals/versioning) | See [versioning](/docs/fundamentals/versioning) for the deprecation policy and API compatibility rules. ## Generation pipeline 1. Source of truth: [packages/openapi/openapi.json](https://github.com/salespie/salespie-payment-portal/blob/development/packages/openapi/openapi.json) 2. Each SDK repo has a GitHub Action that regenerates its client on every spec change 3. A human-authored layer on top of the generated client adds idiomatic retry, pagination, webhook, and error-handling helpers 4. Public releases are cut via `semantic-release` ## Related - **API Reference** (/docs/api-reference): Every endpoint, rendered from the same spec the SDKs are generated from. - **CLI** (/docs/cli): Hit the same API from your terminal. - **MCP server** (/docs/mcp): Expose RevKeen tools to AI hosts over the Model Context Protocol. - **Versioning** (/docs/fundamentals/versioning): API + SDK compatibility matrix. --- # Go SDK Source: https://docs.revkeen.com/docs/sdks/go The official Go client library for the RevKeen API Build and bill on RevKeen from any Go service. Idiomatic `context.Context` plumbing, typed request and response structs, auto-pagination iterators, webhook verification, and production-grade retries. > **Note:** **Repo:** [github.com/RevKeen/sdk-go](https://github.com/RevKeen/sdk-go) · [Releases](https://github.com/RevKeen/sdk-go/releases) · [Issues](https://github.com/RevKeen/sdk-go/issues) · [pkg.go.dev](https://pkg.go.dev/github.com/RevKeen/sdk-go) Generated from [packages/openapi/openapi.json](https://github.com/salespie/salespie-payment-portal/blob/development/packages/openapi/openapi.json). See the [versioning page](/docs/fundamentals/versioning) for the compatibility matrix. ## Install ```bash go get github.com/RevKeen/sdk-go ``` Requires Go 1.21+. ## Quick start ```go package main "context" "fmt" "os" revkeen "github.com/RevKeen/sdk-go" ) func main() { client := revkeen.NewClient(revkeen.Config{ APIKey: os.Getenv("REVKEEN_API_KEY"), }) customer, err := client.Customers.Create(context.Background(), &revkeen.CustomerCreateParams{ Email: revkeen.String("ops@acme.example"), Name: revkeen.String("Acme Inc."), }) if err != nil { panic(err) } fmt.Println(customer.ID) } ``` Every endpoint in the [API reference](/docs/api-reference) is a method on a resource group (`client.Customers`, `client.Invoices`, etc.). ## What's inside - **Typed request and response structs** — no `map[string]interface{}` anywhere - **Context-aware** — every method takes `context.Context` for cancellation and deadlines - **Automatic pagination iterators** — `iter.Next()` / `iter.Current()` / `iter.Err()` - **Automatic retries** — exponential backoff on `5xx`, `429`, network errors - **Idempotency keys** — attached automatically on safe-to-retry mutations - **Webhook verification** — `revkeen.Webhooks.Verify(body, signature, secret)` - **OAuth 2.1 + API-key auth** — both first-class ## Authentication ```go client := revkeen.NewClient(revkeen.Config{ APIKey: os.Getenv("REVKEEN_API_KEY"), }) ``` ```go client := revkeen.NewClient(revkeen.Config{ OAuth: &revkeen.OAuthConfig{ ClientID: os.Getenv("REVKEEN_CLIENT_ID"), ClientSecret: os.Getenv("REVKEEN_CLIENT_SECRET"), Scopes: []string{"customers:read", "invoices:write"}, }, }) ``` ## Common workflows ### Create a customer and invoice ```go ctx := context.Background() customer, _ := client.Customers.Create(ctx, &revkeen.CustomerCreateParams{ Email: revkeen.String("ops@acme.example"), Name: revkeen.String("Acme Inc."), }) invoice, _ := client.Invoices.Create(ctx, &revkeen.InvoiceCreateParams{ CustomerID: revkeen.String(customer.ID), Currency: revkeen.String("USD"), Lines: []revkeen.InvoiceLineParams{{ Description: revkeen.String("Pro plan — January 2026"), UnitAmountMinor: revkeen.Int64(9999), Quantity: revkeen.Int64(1), }}, }) client.Invoices.Finalize(ctx, invoice.ID) client.Invoices.Send(ctx, invoice.ID) ``` ### Iterate with auto-pagination ```go iter := client.Invoices.List(ctx, &revkeen.InvoiceListParams{ Status: revkeen.String("open"), }) for iter.Next() { invoice := iter.Current() fmt.Println(invoice.ID, invoice.AmountDueMinor) } if err := iter.Err(); err != nil { return err } ``` ### Verify a webhook ```go "io" "net/http" "os" revkeen "github.com/RevKeen/sdk-go" ) func webhookHandler(w http.ResponseWriter, r *http.Request) { body, _ := io.ReadAll(r.Body) sig := r.Header.Get("X-RevKeen-Signature") event, err := revkeen.Webhooks.Verify(body, sig, os.Getenv("REVKEEN_WEBHOOK_SECRET")) if err != nil { http.Error(w, "invalid signature", http.StatusBadRequest) return } if event.Type == "invoice.paid" { invoice := event.Data.Object.(*revkeen.Invoice) fulfil(invoice) } w.WriteHeader(http.StatusOK) } ``` See [webhook signing](/docs/webhooks/signing) for the wire format. ## Error handling ```go _, err := client.Customers.Retrieve(ctx, "cus_does_not_exist") var rkErr *revkeen.APIError if errors.As(err, &rkErr) { fmt.Println(rkErr.Code) // "resource_missing" fmt.Println(rkErr.StatusCode) // 404 fmt.Println(rkErr.RequestID) // "req_01HT..." } ``` See the [errors page](/docs/errors) for the full code table. ## Idempotency ```go refund, err := client.Refunds.Create(ctx, &revkeen.RefundCreateParams{ Charge: revkeen.String("ch_01HT..."), AmountMinor: revkeen.Int64(1500), }, revkeen.WithIdempotencyKey(uuid.NewString()), ) ``` See [idempotency](/docs/fundamentals/idempotency) for the replay contract. ## Retries and timeouts ```go client := revkeen.NewClient(revkeen.Config{ APIKey: os.Getenv("REVKEEN_API_KEY"), MaxRetries: 3, // default 2 Timeout: 30 * time.Second, // default 60s }) ``` Retries apply to `5xx`, `429`, and network errors on safe methods. Non-idempotent mutations without an idempotency key never retry. ## Compatibility | Go version | Status | |-----------|--------| | 1.21+ | Supported | | 1.20 | Compile only, some features missing | | 1.19 and earlier | Not supported | API version pinned via `APIVersion` on `Config`. See [versioning](/docs/fundamentals/versioning). ## Resources - **View on GitHub** (https://github.com/RevKeen/sdk-go): Source, issues, release notes. - **pkg.go.dev** (https://pkg.go.dev/github.com/RevKeen/sdk-go): Auto-generated godoc reference. - **API Reference** (/docs/api-reference): Every endpoint, rendered from the OpenAPI spec. - **TypeScript SDK** (/docs/sdks/typescript): Same client shape, in TypeScript. - **PHP SDK** (/docs/sdks/php): Same client shape, in PHP. - **CLI** (/docs/cli): Hit the same API from your terminal. --- # PHP SDK Source: https://docs.revkeen.com/docs/sdks/php The official PHP client library for the RevKeen API Build and bill on RevKeen from any PHP 8.1+ project. PSR-4 autoloading, typed request classes, PSR-3 logging hooks, auto-pagination, webhook verification, and automatic retries. > **Note:** **Repo:** [github.com/RevKeen/sdk-php](https://github.com/RevKeen/sdk-php) · [Releases](https://github.com/RevKeen/sdk-php/releases) · [Issues](https://github.com/RevKeen/sdk-php/issues) · [Packagist](https://packagist.org/packages/revkeen/sdk-php) Generated from [packages/openapi/openapi.json](https://github.com/salespie/salespie-payment-portal/blob/development/packages/openapi/openapi.json). See the [versioning page](/docs/fundamentals/versioning) for the compatibility matrix. ## Install ```bash composer require revkeen/sdk-php ``` Requires PHP 8.1+ with `ext-json` and `ext-mbstring`. ## Quick start ```php getenv('REVKEEN_API_KEY'), ]); $customer = $client->customers->create([ 'email' => 'ops@acme.example', 'name' => 'Acme Inc.', ]); echo $customer->id; ``` Every endpoint in the [API reference](/docs/api-reference) is available as a method on a resource group (`$client->customers`, `$client->invoices`, etc.). ## What's inside - **PSR-4 autoloading** — drop-in for any modern PHP framework - **Typed response objects** — hydrated into typed value classes, not `stdClass` - **PSR-3 logging** — inject any PSR-3 logger to audit requests - **Automatic pagination** — `$client->invoices->autoPagingList()` yields one at a time - **Automatic retries** — exponential backoff on `5xx`, `429`, network errors - **Idempotency keys** — attached automatically on safe-to-retry mutations - **Webhook verification** — `WebhookVerifier::verify($body, $signature, $secret)` - **OAuth 2.1 + API-key auth** — both first-class ## Authentication ```php use RevKeen\RevKeenClient; $client = new RevKeenClient([ 'api_key' => getenv('REVKEEN_API_KEY'), ]); ``` ```php use RevKeen\RevKeenClient; $client = new RevKeenClient([ 'oauth' => [ 'client_id' => getenv('REVKEEN_CLIENT_ID'), 'client_secret' => getenv('REVKEEN_CLIENT_SECRET'), 'scopes' => ['customers:read', 'invoices:write'], ], ]); ``` ## Common workflows ### Create a customer and invoice ```php $customer = $client->customers->create([ 'email' => 'ops@acme.example', 'name' => 'Acme Inc.', ]); $invoice = $client->invoices->create([ 'customer_id' => $customer->id, 'currency' => 'USD', 'lines' => [[ 'description' => 'Pro plan — January 2026', 'unit_amount_minor' => 9999, 'quantity' => 1, ]], ]); $client->invoices->finalize($invoice->id); $client->invoices->send($invoice->id); ``` ### Iterate with auto-pagination ```php foreach ($client->invoices->autoPagingList(['status' => 'open']) as $invoice) { echo $invoice->id . ': ' . $invoice->amount_due_minor . PHP_EOL; } ``` ### Verify a webhook ```php use RevKeen\Webhooks\WebhookVerifier; use RevKeen\Exception\SignatureException; $rawBody = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_REVKEEN_SIGNATURE'] ?? ''; $secret = getenv('REVKEEN_WEBHOOK_SECRET'); try { $event = WebhookVerifier::verify($rawBody, $signature, $secret); if ($event->type === 'invoice.paid') { fulfil($event->data->object); } http_response_code(200); } catch (SignatureException $e) { http_response_code(400); exit('invalid signature'); } ``` See [webhook signing](/docs/webhooks/signing) for the wire format. ## Error handling ```php use RevKeen\Exception\RevKeenException; try { $client->customers->retrieve('cus_does_not_exist'); } catch (RevKeenException $e) { echo $e->getCode(); // "resource_missing" echo $e->getStatusCode(); // 404 echo $e->getRequestId(); // "req_01HT..." throw $e; } ``` See the [errors page](/docs/errors) for the full code table. ## Idempotency ```php use Ramsey\Uuid\Uuid; $refund = $client->refunds->create( [ 'charge' => 'ch_01HT...', 'amount_minor' => 1500, ], ['idempotency_key' => Uuid::uuid4()->toString()], ); ``` See [idempotency](/docs/fundamentals/idempotency) for the replay contract. ## Retries and timeouts ```php $client = new RevKeenClient([ 'api_key' => getenv('REVKEEN_API_KEY'), 'max_retries' => 3, // default 2 'timeout' => 30, // seconds, default 60 ]); ``` Retries apply to `5xx`, `429`, and network errors on safe methods. Non-idempotent mutations without an idempotency key never retry. ## Framework adapters ```php // config/services.php return [ 'revkeen' => [ 'api_key' => env('REVKEEN_API_KEY'), ], ]; // app/Providers/AppServiceProvider.php use RevKeen\RevKeenClient; public function register(): void { $this->app->singleton(RevKeenClient::class, fn () => new RevKeenClient([ 'api_key' => config('services.revkeen.api_key'), ])); } ``` ```php # config/services.yaml services: RevKeen\RevKeenClient: arguments: - api_key: '%env(REVKEEN_API_KEY)%' ``` ```php getenv('REVKEEN_API_KEY'), ]); ``` ## Compatibility | PHP version | Status | |-------------|--------| | 8.3 | Supported | | 8.2 | Supported | | 8.1 | Supported | | 8.0 and earlier | Not supported | API version pinned via `api_version` in the constructor config. See [versioning](/docs/fundamentals/versioning). ## Resources - **View on GitHub** (https://github.com/RevKeen/sdk-php): Source, issues, release notes. - **Packagist** (https://packagist.org/packages/revkeen/sdk-php): `revkeen/sdk-php` on Packagist. - **API Reference** (/docs/api-reference): Every endpoint, rendered from the OpenAPI spec. - **TypeScript SDK** (/docs/sdks/typescript): Same client shape, in TypeScript. - **Go SDK** (/docs/sdks/go): Same client shape, in Go. - **CLI** (/docs/cli): Hit the same API from your terminal. --- # TypeScript SDK Source: https://docs.revkeen.com/docs/sdks/typescript The official TypeScript and JavaScript client library for the RevKeen API Build and bill on RevKeen from any Node.js, Bun, Deno, or TypeScript runtime. Typed end-to-end from the OpenAPI spec, with auto-pagination, automatic retries, webhook verification, and first-class OAuth support. > **Note:** **Repo:** [github.com/RevKeen/sdk-typescript](https://github.com/RevKeen/sdk-typescript) · [Releases](https://github.com/RevKeen/sdk-typescript/releases) · [Issues](https://github.com/RevKeen/sdk-typescript/issues) · [npm](https://www.npmjs.com/package/@revkeen/sdk) Generated from [packages/openapi/openapi.json](https://github.com/salespie/salespie-payment-portal/blob/development/packages/openapi/openapi.json). See the [versioning page](/docs/fundamentals/versioning) for the compatibility matrix. ## Install ```bash npm install @revkeen/sdk ``` ```bash pnpm add @revkeen/sdk ``` ```bash yarn add @revkeen/sdk ``` ```bash bun add @revkeen/sdk ``` Requires Node.js 18+ (or any modern runtime with `fetch`). Ships with full TypeScript definitions — no `@types` package needed. ## Quick start ```typescript const client = new RevKeen({ apiKey: process.env.REVKEEN_API_KEY!, }); const customer = await client.customers.create({ email: "ops@acme.example", name: "Acme Inc.", }); console.log(customer.id); ``` That's it. Every endpoint in the [API reference](/docs/api-reference) is available as a typed method on `client`. ## What's inside - **Fully typed request and response shapes** — autocomplete + compile-time validation for every field - **Automatic pagination** — `for await (const customer of client.customers.list())` - **Automatic retries** — idempotent requests retry on 5xx and network errors with exponential backoff - **Idempotency keys** — attached automatically on safe-to-retry mutations; override per-call - **Webhook verification** — `client.webhooks.verify(rawBody, signature, secret)` in a single line - **OAuth 2.1 + API-key auth** — drop in either, mix per-request if needed - **Runtime-agnostic** — Node.js, Bun, Deno, Cloudflare Workers, Vercel Edge ## Authentication ```typescript // Use `rk_sandbox_*` for sandbox, `rk_live_*` for production. const client = new RevKeen({ apiKey: process.env.REVKEEN_API_KEY!, }); ``` ```typescript // Client-credentials grant — the SDK acquires, caches, and rotates tokens. const client = new RevKeen({ oauth: { clientId: process.env.REVKEEN_CLIENT_ID!, clientSecret: process.env.REVKEEN_CLIENT_SECRET!, scopes: ["customers:read", "invoices:write"], }, }); ``` See the [OAuth guide](/docs/getting-started/oauth) for authorization-code + PKCE, MCP integrations, and the full scope reference. ## Common workflows ### Create a customer and invoice ```typescript const customer = await client.customers.create({ email: "ops@acme.example", name: "Acme Inc.", }); const invoice = await client.invoices.create({ customer_id: customer.id, currency: "USD", lines: [{ description: "Pro plan — January 2026", unit_amount_minor: 9999, quantity: 1, }], }); await client.invoices.finalize(invoice.id); await client.invoices.send(invoice.id); ``` ### Start a hosted checkout ```typescript const session = await client.checkoutSessions.create({ mode: "payment", customer_id: customer.id, success_url: "https://yourapp.com/success", cancel_url: "https://yourapp.com/cancel", line_items: [{ price_id: "price_01HT...", quantity: 1 }], }); return Response.redirect(session.url, 303); ``` ### Iterate with auto-pagination ```typescript // Streams every page automatically — no manual offset tracking. for await (const invoice of client.invoices.list({ status: "open" })) { console.log(invoice.id, invoice.amount_due_minor); } // Or materialise the first N. const first100 = await client.invoices.list({ limit: 100 }).toArray(); ``` ### Verify a webhook ```typescript const client = new RevKeen({ apiKey: process.env.REVKEEN_API_KEY! }); export async function POST(request: Request) { const rawBody = await request.text(); const signature = request.headers.get("x-revkeen-signature"); const secret = process.env.REVKEEN_WEBHOOK_SECRET!; try { const event = client.webhooks.verify(rawBody, signature!, secret); if (event.type === "invoice.paid") { await fulfil(event.data.object); } return new Response(null, { status: 200 }); } catch (err) { if (err instanceof RevKeenError) return new Response(err.message, { status: 400 }); throw err; } } ``` See [webhook signing](/docs/webhooks/signing) for the wire format and replay protection. ## Error handling Every non-`2xx` response throws a typed `RevKeenError` with the same envelope documented on the [errors page](/docs/errors): ```typescript try { await client.customers.retrieve("cus_does_not_exist"); } catch (err) { if (err instanceof RevKeenError) { console.log(err.code); // "resource_missing" console.log(err.status); // 404 console.log(err.requestId); // "req_01HT..." } throw err; } ``` ## Idempotency Mutations automatically carry an idempotency key. Override per-request when you need deterministic retry across processes: ```typescript const refund = await client.refunds.create( { charge: "ch_01HT...", amount_minor: 1500 }, { idempotencyKey: randomUUID() }, ); ``` See [idempotency](/docs/fundamentals/idempotency) for the replay contract. ## Retries and timeouts ```typescript const client = new RevKeen({ apiKey: process.env.REVKEEN_API_KEY!, maxRetries: 3, // default 2 timeout: 30_000, // default 60_000ms }); ``` Retries apply to `5xx`, `429`, and network errors on safe methods. Non-idempotent mutations without an idempotency key never retry. ## Compatibility | Runtime | Status | |---------|--------| | Node.js 18+ | Supported | | Bun 1+ | Supported | | Deno 1.40+ | Supported | | Cloudflare Workers | Supported | | Vercel Edge Runtime | Supported | | Browsers | Not supported — API keys must stay server-side | Package format: ESM and CommonJS. API version pinned via `apiVersion` on the constructor — see [versioning](/docs/fundamentals/versioning). ## Resources - **View on GitHub** (https://github.com/RevKeen/sdk-typescript): Source, issues, and release notes. - **npm package** (https://www.npmjs.com/package/@revkeen/sdk): `@revkeen/sdk` on the npm registry. - **API Reference** (/docs/api-reference): Every endpoint, rendered from the OpenAPI spec. - **Go SDK** (/docs/sdks/go): Same client shape, in Go. - **PHP SDK** (/docs/sdks/php): Same client shape, in PHP. - **CLI** (/docs/cli): Hit the same API from your terminal. --- # RevKeen CLI Source: https://docs.revkeen.com/docs/cli Use the RevKeen command-line client for common billing, payments, and operations workflows The RevKeen CLI is a terminal client for common operator and developer workflows. It ships from the same monorepo as the public API and SDKs and covers billing, customer, payment, webhook, automation, and reporting flows. > **Note:** **Source:** [packages/cli](https://github.com/salespie/salespie-payment-portal/tree/development/packages/cli) The CLI uses a flag-driven command model (`revkeen invoices --list`), not nested subcommands. See the [command reference →](/docs/cli/commands) for every flag and prompt. ## Install ```bash npm install -g @revkeen/cli ``` ```bash pnpm add -g @revkeen/cli ``` ```bash npx @revkeen/cli --help ``` ```bash pnpm --filter @revkeen/cli dev ``` Verify the install: ```bash revkeen --help ``` ## Quick start ```bash # 1. Export an API key export REVKEEN_API_KEY=rk_live_your_api_key # 2. List customers revkeen customers --list # 3. Inspect a specific invoice revkeen invoices --get inv_01HT... # 4. Start an interactive create flow revkeen checkout --create ``` ## How the CLI is shaped ```bash revkeen [mode flag] [arguments] ``` Running `revkeen` with no arguments opens an interactive picker for the main command groups. Each command uses one or more mode flags: ```bash revkeen customers --list revkeen invoices --create revkeen subscriptions --cancel sub_01HT... revkeen automations --approvals ``` ## Commands at a glance | Command | Purpose | Details | |---------|---------|---------| | [`customers`](/docs/cli/commands#customers) | Inspect, create, and update customers | `--list`, `--get`, `--create`, `--update` | | [`products`](/docs/cli/commands#products) | Manage the product catalog | `--list`, `--get`, `--create` | | [`prices`](/docs/cli/commands#prices) | Manage pricing | `--list`, `--get`, `--create` | | [`subscriptions`](/docs/cli/commands#subscriptions) | View and cancel subscriptions | `--list`, `--get`, `--cancel` | | [`invoices`](/docs/cli/commands#invoices) | Full invoice lifecycle | `--list`, `--get`, `--create`, `--finalize`, `--send`, `--void` | | [`payments`](/docs/cli/commands#payments) | Payment intent workflows | `--list`, `--get`, `--create`, `--capture`, `--cancel` | | [`refunds`](/docs/cli/commands#refunds) | Issue full or partial refunds | `--list`, `--get`, `--create` | | [`orders`](/docs/cli/commands#orders) | Full order lifecycle | `--list`, `--get`, `--create`, `--pay`, `--fulfill`, `--cancel` | | [`webhooks`](/docs/cli/commands#webhooks) | Manage webhook endpoints | `--list`, `--create`, `--delete` | | [`entitlements`](/docs/cli/commands#entitlements) | Check customer entitlements | `--list`, `--check` | | [`integrations`](/docs/cli/commands#integrations) | Integration health and sync | `--list`, `--get`, `--sync` | | [`automations`](/docs/cli/commands#automations) | Automation runs and approvals | `--list`, `--get`, `--run`, `--approvals`, `--approve`, `--reject` | | [`analytics`](/docs/cli/commands#analytics) | Read-only reporting | `--mrr`, `--revenue`, `--ar-aging`, `--dso`, `--ltv` | | [`checkout`](/docs/cli/commands#checkout) | Create checkout sessions | `--create` | | [`terminal`](/docs/cli/commands#terminal) | Terminal / POS devices | `--devices`, `--payments`, `--pay` (not yet public) | ## What the CLI is good at today - **Fast inspection** — invoice, customer, payment, and order lookups - **Interactive creation** — invoices, refunds, checkout sessions, webhook endpoints - **Operator tasks** — automation approvals, integration syncs, analytics summaries - **Ad hoc workflows** — when a terminal prompt is faster than the dashboard ## Output format All output is human-readable tables with color-coded status badges. The CLI does not currently support `--json` or `--format` flags. For machine-readable data, use the [REST API →](/docs/api-reference) or an [SDK →](/docs/sdks). Status colors: `paid`/`active`/`succeeded` (green), `open`/`trialing`/`processing` (blue), `paused`/`pending` (yellow), `overdue` (red background), `void`/`cancelled`/`failed` (red), `draft` (gray). ## Recipes Common multi-command workflows: ```bash # Invoice lifecycle: create → finalize → send revkeen invoices --create revkeen invoices --finalize inv_01HT... revkeen invoices --send inv_01HT... # Review and approve automation actions revkeen automations --approvals revkeen automations --approve apr_01HT... # Check a customer's subscriptions and entitlements revkeen subscriptions --list revkeen entitlements --list cus_01HT... # Trigger an integration sync and check analytics revkeen integrations --sync xero revkeen analytics --mrr ``` ## See also - **Authentication**: API keys, interactive prompt flow, and base URL overrides. - **Command reference**: Every command, flag, interactive prompt, and sample output. - **API Reference**: Canonical REST contract backing the SDKs and CLI. - **SDKs**: Use the official clients for application code. --- # CLI Authentication Source: https://docs.revkeen.com/docs/cli/authentication Authenticate the RevKeen CLI with API keys and environment overrides The current RevKeen CLI reads an API key from the environment and falls back to an interactive prompt if no key is set. ## How authentication works 1. If `REVKEEN_API_KEY` is set, the CLI uses it. 2. If no environment variable is present, the CLI prompts you to paste a key interactively. 3. The key must start with `rk_`. There is no persisted profile or OAuth login flow in the current CLI implementation. ## Preferred setup Set the API key in your shell before running commands: ```bash export REVKEEN_API_KEY=rk_live_your_api_key revkeen customers --list ``` ```powershell $env:REVKEEN_API_KEY = "rk_live_your_api_key" revkeen customers --list ``` ## Interactive fallback If the environment variable is missing, the CLI prompts for a key: ```text Enter your RevKeen API key: ``` That is useful for one-off sessions, but environment variables are better for repeatable developer workflows and CI. ## Base URL override The CLI defaults to the production API: ```text https://api.revkeen.com ``` To point the CLI at another environment, set `REVKEEN_API_URL`: ```bash export REVKEEN_API_KEY=rk_sandbox_your_api_key export REVKEEN_API_URL=https://staging-api.revkeen.com revkeen invoices --list ``` ```powershell $env:REVKEEN_API_KEY = "rk_sandbox_your_api_key" $env:REVKEEN_API_URL = "https://staging-api.revkeen.com" revkeen invoices --list ``` Use the base URL override deliberately. The CLI does not currently maintain named profiles or environment aliases for you. ## CI usage In CI, provide the API key as an environment variable: ```yaml - name: List invoices env: REVKEEN_API_KEY: ${{ secrets.REVKEEN_API_KEY }} run: revkeen invoices --list ``` ## Security guidance - Use staging keys during development and live keys only for production operations. - Prefer environment variables or a secret manager over ad hoc copy-paste on shared machines. - Rotate keys regularly from the RevKeen dashboard. - Avoid echoing keys into logs or shell history. ## See also - **CLI overview**: Install and use the current CLI surface. - **Command reference**: Full flag, prompt, and output reference for every command. - **REST authentication**: Understand API keys and server-side auth in the broader platform. --- # Command Reference Source: https://docs.revkeen.com/docs/cli/commands Full command reference for the RevKeen CLI — flags, interactive prompts, and sample output This page documents every command in the RevKeen CLI as implemented in `packages/cli/src/`. ## Command pattern ```bash revkeen [mode flag] [arguments] ``` Running `revkeen` with no arguments opens an interactive picker. ## Global options These flags are available on every command: | Flag | Description | |------|-------------| | `--help`, `-h` | Show help for the command | | `--version`, `-V` | Print CLI version | > **Note:** The CLI does not currently support `--json`, `--verbose`, `--quiet`, or `--format` flags. All output is human-readable tables powered by `cli-table3`. For machine-readable data, use the [REST API →](/docs/api-reference) or an [SDK →](/docs/sdks) directly. ## Environment variables | Variable | Default | Description | |----------|---------|-------------| | `REVKEEN_API_KEY` | — | API key (must start with `rk_`). If unset, the CLI prompts interactively. | | `REVKEEN_API_URL` | `https://api.revkeen.com` | Override the API base URL for staging or internal environments. | See [CLI authentication →](/docs/cli/authentication) for full details. --- ## customers Inspect, create, and update customers. ```bash revkeen customers [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List customers (limit 20) | | `--get ` | Get a customer by ID (prints JSON) | | `--create` | Create a customer interactively | | `--update ` | Update a customer interactively | ### Interactive prompts (`--create`) | Prompt | Placeholder | Required | |--------|-------------|----------| | Customer name | `John Doe` | Yes | | Customer email | `john@example.com` | Yes | | Phone (optional) | `+44...` | No | ### Interactive prompts (`--update`) | Prompt | Default | Note | |--------|---------|------| | New name (leave empty to skip) | empty | Skips if blank | | New email (leave empty to skip) | empty | Skips if blank | ### Examples ```bash revkeen customers --list ``` ```text ┌──────────────────┬──────────────┬───────────────────────┬────────────┐ │ ID │ Name │ Email │ Created │ ├──────────────────┼──────────────┼───────────────────────┼────────────┤ │ cus_01HT3N... │ Jane Smith │ jane@acme.com │ 2026-03-12 │ │ cus_01HT4P... │ Bob Wilson │ bob@example.com │ 2026-03-10 │ └──────────────────┴──────────────┴───────────────────────┴────────────┘ ``` ```bash revkeen customers --get cus_01HT3N... ``` Prints the full customer JSON from the API. --- ## products Manage the product catalog. ```bash revkeen products [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List products (limit 20) | | `--get ` | Get a product by ID (prints JSON) | | `--create` | Create a product interactively | ### Interactive prompts (`--create`) | Prompt | Placeholder | Required | Notes | |--------|-------------|----------|-------| | Product ID (slug) | `my-product` | Yes | URL-safe identifier | | Product name | — | Yes | Display name | | Description (optional) | — | No | | | Product kind | — | Yes | Select: One-time, Subscription, Usage-based | | Amount (in minor units) | `1000` | Yes | `1000` = 10.00. Must be non-negative. | ### Examples ```bash revkeen products --list ``` ```text ┌──────────────────┬──────────────────┬─────────────────────────┐ │ ID │ Name │ Description │ ├──────────────────┼──────────────────┼─────────────────────────┤ │ prod_monthly │ Monthly Plan │ Standard monthly access │ │ prod_annual │ Annual Plan │ Discounted annual plan │ └──────────────────┴──────────────────┴─────────────────────────┘ ``` --- ## prices Manage pricing for products. ```bash revkeen prices [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List prices (limit 20) | | `--get ` | Get a price by ID (prints JSON) | | `--create` | Create a price interactively | ### Examples ```bash revkeen prices --list revkeen prices --get prc_01HT... ``` --- ## subscriptions View and cancel subscriptions. ```bash revkeen subscriptions [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List subscriptions (limit 20) | | `--get ` | Get a subscription by ID (prints JSON) | | `--cancel ` | Cancel a subscription (prompts for confirmation) | ### Interactive prompts (`--cancel`) | Prompt | Type | |--------|------| | Cancel subscription \{id\}? | Confirm (yes/no) | ### Examples ```bash revkeen subscriptions --list ``` ```text ┌──────────────────┬──────────────┬──────────┬─────────────┐ │ ID │ Customer │ Status │ Period End │ ├──────────────────┼──────────────┼──────────┼─────────────┤ │ sub_01HT... │ cus_01HT3N.. │ active │ 2026-05-12 │ │ sub_01HT... │ cus_01HT4P.. │ paused │ 2026-04-30 │ └──────────────────┴──────────────┴──────────┴─────────────┘ ``` Status values are color-coded: `active` (green), `paused`/`pending` (yellow), `cancelled` (red), `trialing` (blue). --- ## invoices Full invoice lifecycle — create, finalize, send, and void. ```bash revkeen invoices [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List invoices (limit 20) | | `--get ` | Get an invoice by ID (prints JSON) | | `--create` | Create a draft invoice interactively | | `--finalize ` | Finalize a draft invoice (optionally auto-send) | | `--send ` | Send a finalized invoice | | `--void ` | Void an invoice (prompts for confirmation, irreversible) | ### Interactive prompts (`--create`) | Prompt | Placeholder | Required | Notes | |--------|-------------|----------|-------| | Customer ID | `cus_xxx` | Yes | | | Total amount (in minor units) | `1000` | Yes | `1000` = 10.00. Must be non-negative. | | Currency | — | Yes | Select: GBP, USD, EUR | ### Interactive prompts (`--finalize`) | Prompt | Default | |--------|---------| | Auto-send the invoice after finalizing? | No | ### Interactive prompts (`--void`) | Prompt | Type | |--------|------| | Void invoice \{id\}? This cannot be undone. | Confirm (yes/no) | ### Examples ```bash revkeen invoices --list ``` ```text ┌──────────────────┬──────────────┬──────────┬────────────┬──────────┬────────────┐ │ ID │ Customer │ Status │ Amount Due │ Currency │ Due Date │ ├──────────────────┼──────────────┼──────────┼────────────┼──────────┼────────────┤ │ inv_01HT... │ cus_01HT3N.. │ paid │ 150.00 │ GBP │ 2026-04-01 │ │ inv_01HT... │ cus_01HT4P.. │ open │ 75.00 │ USD │ 2026-04-15 │ │ inv_01HT... │ cus_01HT5Q.. │ overdue │ 200.00 │ EUR │ 2026-03-20 │ └──────────────────┴──────────────┴──────────┴────────────┴──────────┴────────────┘ ``` Status values are color-coded: `paid` (green), `open` (blue), `draft` (gray), `overdue` (red background), `void` (red). ```bash # Create, finalize, and send an invoice revkeen invoices --create # outputs inv_01HT... revkeen invoices --finalize inv_01HT... revkeen invoices --send inv_01HT... ``` --- ## payments Manage payment intents — create, capture authorized payments, and cancel. ```bash revkeen payments [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List payment intents (limit 20) | | `--get ` | Get a payment intent by ID (prints JSON) | | `--create` | Create a payment intent interactively | | `--capture ` | Capture an authorized payment | | `--cancel ` | Cancel a payment intent | ### Examples ```bash revkeen payments --list revkeen payments --get pi_01HT... revkeen payments --capture pi_01HT... ``` --- ## refunds Issue full or partial refunds. ```bash revkeen refunds [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List refunds (limit 20) | | `--get ` | Get a refund by ID (prints JSON) | | `--create` | Create a refund interactively | ### Interactive prompts (`--create`) | Prompt | Placeholder | Required | Notes | |--------|-------------|----------|-------| | Payment ID to refund | `txn_xxx` | Yes | | | Amount to refund in minor units | `1000` | No | Leave empty for a full refund | | Reason for refund | — | Yes | Select: No reason, Duplicate charge, Fraudulent, Requested by customer | ### Examples ```bash revkeen refunds --list ``` ```text ┌──────────────────┬──────────┬──────────┬───────────┬──────────────────────┐ │ ID │ Amount │ Currency │ Status │ Reason │ ├──────────────────┼──────────┼──────────┼───────────┼──────────────────────┤ │ ref_01HT... │ 50.00 │ GBP │ succeeded │ Requested by customer│ │ ref_01HT... │ 150.00 │ USD │ pending │ Duplicate charge │ └──────────────────┴──────────┴──────────┴───────────┴──────────────────────┘ ``` --- ## orders Full order lifecycle — create, pay, fulfill, and cancel. ```bash revkeen orders [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List orders (limit 20) | | `--get ` | Get an order by ID (prints JSON) | | `--create` | Create an order interactively | | `--pay ` | Mark an order as paid | | `--fulfill ` | Mark an order as fulfilled | | `--cancel ` | Cancel an order | ### Examples ```bash revkeen orders --list revkeen orders --pay ord_01HT... revkeen orders --fulfill ord_01HT... ``` --- ## webhooks Manage webhook endpoints and event subscriptions. ```bash revkeen webhooks [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List webhook endpoints (limit 20) | | `--create` | Create a webhook endpoint interactively | | `--delete ` | Delete a webhook endpoint (prompts for confirmation) | ### Interactive prompts (`--create`) | Prompt | Placeholder | Required | Notes | |--------|-------------|----------|-------| | Webhook URL | `https://example.com/webhooks` | Yes | Must be a valid URL | | Select events to listen for | — | Yes | Multi-select from 30+ event types | Available event categories: `invoice.*`, `payment_intent.*`, `customer.*`, `subscription.*`, `order.*`, `refund.*`, `charge.*`, `checkout.session.completed` ### Examples ```bash revkeen webhooks --list ``` ```text ┌──────────────────┬──────────────────────────────────┬────────┬──────────┐ │ ID │ URL │ Events │ Status │ ├──────────────────┼──────────────────────────────────┼────────┼──────────┤ │ we_01HT... │ https://acme.com/webhooks │ 5 │ active │ │ we_01HT... │ https://example.com/hooks/revkeen│ 12 │ active │ └──────────────────┴──────────────────────────────────┴────────┴──────────┘ ``` > **Note:** When you create a webhook endpoint, the CLI prints a **signing secret**. Store it immediately — it will not be shown again. --- ## entitlements Check what a customer is entitled to. ```bash revkeen entitlements [options] ``` ### Options | Flag | Description | |------|-------------| | `--list ` | List entitlements for a customer | | `--check` | Check a specific entitlement interactively | ### Examples ```bash revkeen entitlements --list cus_01HT3N... ``` --- ## integrations View integration status and trigger syncs. ```bash revkeen integrations [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List connected integrations | | `--get ` | Get integration details by provider name | | `--sync ` | Trigger a manual sync for a provider | Supported providers: `xero`, `quickbooks`, `practicehub` ### Examples ```bash revkeen integrations --list revkeen integrations --sync xero ``` --- ## automations Manage automations, view runs, and handle approval workflows. ```bash revkeen automations [options] ``` ### Options | Flag | Description | |------|-------------| | `--list` | List automations | | `--get ` | Get automation details (prints name, status, trigger, risk, objective) | | `--run ` | Queue a manual automation run | | `--runs ` | List runs for an automation | | `--run-detail ` | Get details for a specific run (prints summary, step count, approval count) | | `--approvals` | List pending and historical approvals | | `--approve ` | Approve an automation approval | | `--reject ` | Reject an automation approval | | `--reason ` | Reason for rejection (used with `--reject`) | ### Examples ```bash revkeen automations --list ``` ```text ┌──────────────────┬───────────────────────┬──────────┬──────────────┬────────┐ │ ID │ Name │ Status │ Trigger │ Risk │ ├──────────────────┼───────────────────────┼──────────┼──────────────┼────────┤ │ auto_01HT... │ Dunning follow-up │ active │ invoice.overdue │ medium │ │ auto_01HT... │ Welcome onboarding │ active │ customer.created│ low │ └──────────────────┴───────────────────────┴──────────┴──────────────┴────────┘ ``` ```bash # Review and approve pending automation approvals revkeen automations --approvals revkeen automations --approve apr_01HT... # Reject with a reason revkeen automations --reject apr_01HT... --reason "Needs manual review first" ``` --- ## analytics Read-only reporting summaries. ```bash revkeen analytics [options] ``` ### Options | Flag | Description | |------|-------------| | `--mrr` | View Monthly Recurring Revenue summary | | `--revenue` | View revenue time series (prompts for date range) | | `--ar-aging` | View accounts receivable aging buckets | | `--dso` | View days sales outstanding | | `--ltv` | View customer lifetime value | ### Interactive prompts (`--revenue`) | Prompt | Placeholder | |--------|-------------| | Start date (ISO 8601) | `2026-01-01` | | End date (ISO 8601) | `2026-12-31` | ### Examples ```bash revkeen analytics --mrr ``` ```text Monthly Recurring Revenue ───────────────────────────── MRR: 10,000.00 Previous: 9,500.00 Growth: ↑ 500.00 New MRR: 1,200.00 Churned MRR: 700.00 ``` ```bash revkeen analytics --dso ``` DSO values are color-coded: 30 or under (green), 31–60 (yellow), over 60 (red). ```bash revkeen analytics --ltv ``` ```text Average LTV: 1,250.00 Median LTV: 980.00 ``` --- ## checkout Create hosted checkout sessions. ```bash revkeen checkout [options] ``` ### Options | Flag | Description | |------|-------------| | `--create` | Create a checkout session interactively | ### Examples ```bash revkeen checkout --create ``` --- ## terminal Terminal / POS device management. ```bash revkeen terminal [options] ``` ### Options | Flag | Description | |------|-------------| | `--devices` | List terminal devices | | `--payments` | List terminal payments | | `--pay` | Create a terminal payment interactively | > **Note:** Terminal commands are not yet available in the public CLI. Use the dashboard or connector SDK for terminal operations. --- ## Error handling The CLI surfaces errors as inline messages. Common cases: | Scenario | Output | |----------|--------| | Missing API key (no env var) | Interactive prompt: "Enter your RevKeen API key:" | | Invalid API key format | Validation error (key must start with `rk_`) | | API error (401, 404, 500) | Prints the error message from the API response | | No results | "No \{resource\} found." | | No flag specified | "Use --list, --get \, ..." help text | The CLI does not currently have specific handling for rate limiting — rate limit errors bubble up as API error messages. --- ## Limitations - All list commands return a maximum of 20 results with no pagination flags - No `--json` output mode — use the [REST API →](/docs/api-reference) or [SDKs →](/docs/sdks) for machine-readable data - No filtering flags (e.g. `--status`, `--customer-id`) - No `login` / `logout` / `config` commands — authentication is env-var based - No `--no-color` flag — colors are always enabled - No webhook event replay or delivery history viewing ## See also - **CLI overview**: Installation and quick start. - **CLI authentication**: Environment variables and base URL overrides. - **API Reference**: Canonical REST contract behind the broader platform. --- # Webhooks Source: https://docs.revkeen.com/docs/webhooks Receive and verify RevKeen webhook events Webhooks push event notifications to your application when something changes in RevKeen — a payment succeeded, an invoice was paid, a subscription renewed. They are the correct way to keep your system in sync without polling. > **Note:** Test webhook delivery in **Staging**. The mock server does not emit events. ## Operational model 1. **Create an endpoint** in the dashboard or via the [Webhook Endpoints API](/docs/api-reference). Select the event types you care about. 2. **RevKeen signs and POSTs** each event as it occurs. 3. **Your server verifies the signature**, logs the event ID, and returns `2xx` quickly. 4. **Downstream work happens asynchronously** after acknowledgement. ## The event envelope Every webhook delivery uses the same envelope: ```json { "id": "evt_1a2b3c4d5e6f", "type": "payment.succeeded", "created": 1705689600, "livemode": true, "data": { "object": { /* the affected resource — a Payment, Invoice, Subscription, etc. */ }, "previous_attributes": { /* for update events, the values that changed */ } } } ``` | Field | Type | Description | |-------|------|-------------| | `id` | `string` | Unique event identifier. Use this for deduplication. | | `type` | `string` | Event type using dot notation (e.g., `payment.succeeded`). | | `created` | `integer` | Unix timestamp when the event was created. | | `livemode` | `boolean` | `true` for production, `false` for staging. | | `data.object` | `object` | The resource that triggered the event. | | `data.previous_attributes` | `object` | On `*.updated` events only — the changed fields. | ## What's next - **Verify signatures** (/docs/webhooks/signing): HMAC verification, timestamp tolerance, replay-attack prevention. - **Retry behavior** (/docs/webhooks/retry-behavior): Delivery retry schedule, dead-letter behaviour, idempotency. - **Event catalogue** (/docs/webhooks/events): Every event type RevKeen emits, with payload schemas. - **Webhook Endpoints API** (/docs/api-reference): Create, update, and test endpoints via the REST API. --- # Event catalogue Source: https://docs.revkeen.com/docs/webhooks/events Every webhook event type RevKeen emits Every webhook event uses [the standard envelope](/docs/webhooks#the-event-envelope). The table below lists every event type currently emitted, grouped by resource. Subscribe to the events you care about when [creating a webhook endpoint](/docs/api-reference) — do not subscribe to `*`. Fine-grained subscriptions are cheaper, faster, and easier to debug. ## Payments | Event | When it fires | `data.object` | |-------|---------------|---------------| | `payment.succeeded` | Gateway confirmed a successful capture. | `Payment` | | `payment.failed` | Gateway declined, returned an error, or timed out. | `Payment` | | `payment.refunded` | Full or partial refund was issued. | `Payment` | | `payment.voided` | Pre-settlement void succeeded. | `Payment` | | `charge.captured` | Auth was captured (deferred capture flows). | `Charge` | | `charge.dispute.created` | Cardholder initiated a dispute / chargeback. | `Dispute` | | `charge.dispute.updated` | Dispute state changed (evidence required, won, lost). | `Dispute` | | `refund.created` | Refund was accepted by the gateway. | `Refund` | | `refund.succeeded` | Refund settled successfully. | `Refund` | | `refund.failed` | Refund rejected or settlement failed. | `Refund` | See the [`payment.succeeded` example](/docs/webhooks/events/payment-succeeded) for a full payload. ## Invoices | Event | When it fires | `data.object` | |-------|---------------|---------------| | `invoice.finalized` | Invoice moved from `draft` to `open`. | `Invoice` | | `invoice.sent` | Invoice email / SMS / WhatsApp was sent to the customer. | `Invoice` | | `invoice.paid` | Invoice fully paid. | `Invoice` | | `invoice.payment_failed` | A collection attempt failed — entry point to dunning. | `Invoice` | | `invoice.voided` | Invoice was voided before payment. | `Invoice` | | `invoice.uncollectible` | Invoice written off after failed collection. | `Invoice` | | `credit_note.issued` | Credit note issued against a paid invoice. | `CreditNote` | See the [`invoice.paid` example](/docs/webhooks/events/invoice-paid) for a full payload. ## Subscriptions | Event | When it fires | `data.object` | |-------|---------------|---------------| | `subscription.created` | A new subscription was started. | `Subscription` | | `subscription.updated` | Any field changed (plan, quantity, metadata). | `Subscription` | | `subscription.renewed` | A renewal cycle was billed. | `Subscription` | | `subscription.canceled` | Subscription was cancelled (immediate or end-of-period). | `Subscription` | | `subscription.paused` | Subscription paused via dashboard or API. | `Subscription` | | `subscription.resumed` | Previously paused subscription was resumed. | `Subscription` | | `subscription.trial_will_end` | Fires 3 days before trial end. | `Subscription` | See the [`subscription.updated` example](/docs/webhooks/events/subscription-updated) for a full payload. ## Customers | Event | When it fires | `data.object` | |-------|---------------|---------------| | `customer.created` | Customer record created. | `Customer` | | `customer.updated` | Customer attributes changed. | `Customer` | | `customer.deleted` | Customer was hard-deleted. | `Customer` | ## Checkout | Event | When it fires | `data.object` | |-------|---------------|---------------| | `checkout.session.completed` | Hosted checkout session was paid. | `CheckoutSession` | | `checkout.session.expired` | Session hit its TTL without payment. | `CheckoutSession` | | `payment_link.completed` | Customer completed a payment link flow. | `PaymentLink` | ## Payouts | Event | When it fires | `data.object` | |-------|---------------|---------------| | `payout.paid` | Funds settled to the merchant's bank account. | `Payout` | | `payout.failed` | Payout rejected by the acquiring bank. | `Payout` | ## Terminal (card-present) | Event | When it fires | `data.object` | |-------|---------------|---------------| | `terminal_payment.succeeded` | Card-present terminal charge completed. | `TerminalPayment` | | `terminal_payment.failed` | Terminal charge declined or timed out. | `TerminalPayment` | ## Wallet & credits | Event | When it fires | `data.object` | |-------|---------------|---------------| | `wallet.credit_issued` | Credit was added to a customer's wallet. | `Wallet` | | `wallet.code_created` | Redemption code was minted. | `WalletCode` | | `benefits.granted` | Entitlement granted to a customer. | `Entitlement` | ## Entitlements & usage | Event | When it fires | `data.object` | |-------|---------------|---------------| | `usage.threshold_reached` | Customer exceeded a configured usage threshold. | `UsageSnapshot` | | `entitlement.expired` | Time-bounded entitlement ended. | `Entitlement` | ## Delivery failures (meta) | Event | When it fires | `data.object` | |-------|---------------|---------------| | `endpoint.delivery.failed` | A webhook endpoint had 3+ consecutive retry failures. | `WebhookEndpoint` | Subscribe to this from a **separate** webhook endpoint (or an out-of-band alerting system) so you learn about outages on your primary endpoint. ## Event versioning Event payloads follow the same [API versioning](/docs/fundamentals/versioning) rules — new fields can appear at any time, existing fields never change meaning under an existing version header. Pin the endpoint's version when you create it via the dashboard or API. ## See also - **Verify signatures** (/docs/webhooks/signing): Required before you act on any event. - **Retry behavior** (/docs/webhooks/retry-behavior): What happens when your endpoint fails. - **Webhook Endpoints API** (/docs/api-reference): Create, update, test endpoints via REST. --- # invoice.paid Source: https://docs.revkeen.com/docs/webhooks/events/invoice-paid Fires when an invoice is fully settled Fires when an invoice's `status` transitions to `paid`. This is the canonical entry point for post-billing fulfilment on recurring plans. > **Note:** `invoice.paid` and [`payment.succeeded`](/docs/webhooks/events/payment-succeeded) are two views of the same money movement. Choose one based on your handler: - **Digital fulfilment** → `invoice.paid` (post-tax, post-discount amount is on the invoice) - **Ledger reconciliation** → `payment.succeeded` (gateway-level truth) If you act on both, deduplicate by `invoice.id` to avoid double-fulfilling. ## Payload ```json { "id": "evt_1a2b3c4d5e6f", "type": "invoice.paid", "created": 1705689600, "livemode": true, "data": { "object": { "id": "inv_01HK4X7Z2M5N8P0Q3R6S9T2V5", "object": "invoice", "number": "INV-2026-00042", "status": "paid", "customer_id": "cus_01HK4X7Z2M5N8P0Q3R6S9T2V5", "subscription_id": "sub_01HK4X7Z2M5N8P0Q3R6S9T2V5", "amount_due_minor": 9999, "amount_paid_minor": 9999, "amount_remaining_minor": 0, "currency": "USD", "due_date": "2026-01-31", "paid_at": "2026-01-19T12:00:00Z", "lines": [ { "id": "il_01HK4X7Z2M5N8P0Q3R6S9T2V5", "description": "Professional plan — January 2026", "quantity": 1, "unit_amount_minor": 9999, "subtotal_minor": 9999 } ], "metadata": {} }, "previous_attributes": { "status": "open", "amount_paid_minor": 0, "amount_remaining_minor": 9999 } } } ``` ## Handler contract 1. Verify the signature. 2. Deduplicate by `event.id`. 3. If `subscription_id` is set → refresh the subscription's service entitlement window. 4. If the invoice has digital-delivery line items → run delivery. 5. Send a receipt if your billing doesn't already do that (RevKeen's dispatch system handles receipts by default — opt out with `automatic_receipt: false` on the subscription). 6. Return `2xx`. ## `previous_attributes` For update-style events, `data.previous_attributes` lists what changed. For `invoice.paid`, expect: ```json { "status": "open", "amount_paid_minor": 0, "amount_remaining_minor": 9999 } ``` Do not rely on this for state reconstruction — always read the current state from `data.object`. ## Related events - [`invoice.finalized`](/docs/webhooks/events) — the invoice became billable - [`invoice.payment_failed`](/docs/webhooks/events) — collection failed (dunning entry) - [`invoice.voided`](/docs/webhooks/events) — invoice cancelled before payment - [`subscription.renewed`](/docs/webhooks/events/subscription-updated) — matching subscription-level event --- # payment.succeeded Source: https://docs.revkeen.com/docs/webhooks/events/payment-succeeded Fires when a gateway confirms a successful capture Fires when the gateway confirms a successful capture. This is the canonical "money moved" event. > **Note:** For recurring billing, `payment.succeeded` is paired with [`invoice.paid`](/docs/webhooks/events/invoice-paid) — the payment succeeded **and** the invoice it settles was marked paid. Deduplicate by `invoice.id` if you trigger fulfilment from both. ## Payload ```json { "id": "evt_1a2b3c4d5e6f", "type": "payment.succeeded", "created": 1705689600, "livemode": true, "data": { "object": { "id": "pay_01HK4X7Z2M5N8P0Q3R6S9T2V5", "object": "payment", "amount_minor": 2499, "currency": "USD", "status": "succeeded", "customer_id": "cus_01HK4X7Z2M5N8P0Q3R6S9T2V5", "invoice_id": "inv_01HK4X7Z2M5N8P0Q3R6S9T2V5", "payment_method_id": "pm_01HK4X7Z2M5N8P0Q3R6S9T2V5", "gateway_transaction_id": "ch_3Nk7mL2eZvKYlo2C1abc", "gateway": "nmi", "captured_at": "2026-01-19T12:00:00Z", "metadata": { "order_id": "ord_12345" } } } } ``` ## Handler contract 1. Verify the signature (always). 2. Deduplicate by `event.id`. 3. If this payment settles an invoice → look up the invoice, confirm its state is `paid`, run your fulfilment flow. 4. If this payment is standalone → grant the benefit / deliver the digital good / mark the order paid. 5. Return `2xx` within 30 seconds; push anything slower to a queue. ## Handler example ```ts const client = new RevKeen({ apiKey: process.env.REVKEEN_API_KEY! }); export async function handleWebhook(request: Request) { const rawBody = await request.text(); const sig = request.headers.get("x-revkeen-signature")!; const secret = process.env.REVKEEN_WEBHOOK_SECRET!; const event = client.webhooks.verify(rawBody, sig, secret); if (event.type === "payment.succeeded") { const payment = event.data.object; if (await alreadyProcessed(event.id)) return new Response(null, { status: 200 }); await fulfillOrder({ paymentId: payment.id, amountMinor: payment.amount_minor, currency: payment.currency, orderId: payment.metadata.order_id, }); await markProcessed(event.id); } return new Response(null, { status: 200 }); } ``` ```go func handleWebhook(w http.ResponseWriter, r *http.Request) { body, _ := io.ReadAll(r.Body) sig := r.Header.Get("X-RevKeen-Signature") event, err := revkeen.Webhooks.Verify(body, sig, os.Getenv("REVKEEN_WEBHOOK_SECRET")) if err != nil { http.Error(w, "invalid signature", http.StatusBadRequest) return } if event.Type == "payment.succeeded" { if alreadyProcessed(event.ID) { w.WriteHeader(http.StatusOK) return } payment := event.Data.Object.(*revkeen.Payment) fulfillOrder(payment) markProcessed(event.ID) } w.WriteHeader(http.StatusOK) } ``` ```php use RevKeen\Webhooks\WebhookVerifier; $rawBody = file_get_contents('php://input'); $sig = $_SERVER['HTTP_X_REVKEEN_SIGNATURE'] ?? ''; $event = WebhookVerifier::verify($rawBody, $sig, getenv('REVKEEN_WEBHOOK_SECRET')); if ($event->type === 'payment.succeeded') { if (alreadyProcessed($event->id)) { http_response_code(200); exit; } $payment = $event->data->object; fulfillOrder($payment); markProcessed($event->id); } http_response_code(200); ``` ## Common gotchas - **Do not grant the benefit before verifying.** An attacker can POST a fake `payment.succeeded` — signature verification is the only thing that makes this event trustworthy. - **Do not assume `invoice_id` is populated.** Standalone charges (one-time payments, payment links) have no invoice. Check for null. - **Do not read `amount` — read `amount_minor`.** All money in RevKeen is in minor units (cents, pence, öre). Human-readable amounts are derived on display. ## Related events - [`payment.failed`](/docs/webhooks/events) — use for dunning entry - [`invoice.paid`](/docs/webhooks/events/invoice-paid) — recurring billing equivalent - [`refund.created`](/docs/webhooks/events) — reverse of this event --- # subscription.updated Source: https://docs.revkeen.com/docs/webhooks/events/subscription-updated Fires whenever any field on a subscription changes Fires whenever any field on a subscription changes — plan swap, quantity bump, metadata edit, status transition. The envelope's `data.previous_attributes` tells you what changed. > **Note:** This event fires **often**. Subscribe to it only if your consumer needs to react to every state delta. For lifecycle-only consumers, subscribe to the narrower events: `subscription.created`, `subscription.canceled`, `subscription.renewed`, `subscription.paused`, `subscription.resumed`. ## Payload ```json { "id": "evt_1a2b3c4d5e6f", "type": "subscription.updated", "created": 1705689600, "livemode": true, "data": { "object": { "id": "sub_01HK4X7Z2M5N8P0Q3R6S9T2V5", "object": "subscription", "status": "active", "customer_id": "cus_01HK4X7Z2M5N8P0Q3R6S9T2V5", "price_id": "price_01HK4X7Z2M5N8P0Q3R6S9T2V5", "quantity": 5, "current_period_start": "2026-01-01T00:00:00Z", "current_period_end": "2026-02-01T00:00:00Z", "cancel_at_period_end": false, "trial_end": null, "metadata": {} }, "previous_attributes": { "quantity": 3 } } } ``` ## Common triggers | Change | What changed in `previous_attributes` | |--------|---------------------------------------| | Plan swap | `price_id`, `quantity` | | Seat change | `quantity` | | Pause | `status: active` → `status: paused` | | Resume | `status: paused` → `status: active` | | Schedule cancellation | `cancel_at_period_end: false` | | Renewal | `current_period_start`, `current_period_end` | | Trial → active | `status: trialing` or `trial_end` | ## Handler contract 1. Verify the signature. 2. Deduplicate by `event.id`. 3. Read `data.object` for the current state — do **not** reconstruct state from `previous_attributes`. 4. If `status: canceled` and your entitlement model cuts off immediately → revoke access. 5. If `cancel_at_period_end: true` → mark the account to revoke at `current_period_end` (via scheduled job or cron). 6. Return `2xx`. ## Narrower alternatives If you only care about: - **Cancellation** → subscribe to `subscription.canceled`, not `subscription.updated` - **Renewals** → subscribe to `subscription.renewed` (fires after the payment succeeds for the new period) - **Trial ending** → subscribe to `subscription.trial_will_end` (fires 3 days before the end) Narrower subscriptions = fewer handler invocations + less dedup work. ## Related events - [`subscription.created`](/docs/webhooks/events) — new subscription - [`subscription.canceled`](/docs/webhooks/events) — fully cancelled - [`subscription.renewed`](/docs/webhooks/events) — renewal succeeded - [`subscription.trial_will_end`](/docs/webhooks/events) — 3-day warning - [`invoice.paid`](/docs/webhooks/events/invoice-paid) — matching invoice-level event on renewals --- # Retry behavior Source: https://docs.revkeen.com/docs/webhooks/retry-behavior Delivery retry schedule, dead-letter policy, and idempotency RevKeen retries failed webhook deliveries automatically. Your consumer just needs to be idempotent and return `2xx` quickly on success. ## Retry schedule A delivery is considered failed if your endpoint returns non-`2xx`, times out after 30 seconds, or refuses the connection. | Attempt | Delay after previous failure | |--------:|------------------------------| | 1 | Immediate (the original delivery) | | 2 | 5 minutes | | 3 | 30 minutes | | 4 | 2 hours | | 5 | 8 hours | | 6 | 24 hours | After 6 attempts RevKeen stops retrying and marks the delivery as **dead**. Dead deliveries are visible on the endpoint in the dashboard for 30 days before archival. ## What counts as a failure | Response | Retried? | |----------|----------| | `2xx` | No — success. | | `3xx` | Yes — treat as a failure. Do not redirect. | | `4xx` | Yes — but consider it a bug on your side; alert. | | `5xx` | Yes. | | Timeout (>30s) | Yes. | | Connection refused / DNS failure | Yes. | | TLS handshake failure | Yes. | ## Idempotency contract Every delivery attempt uses the **same event `id`**. Retries do not produce new event IDs. ```json { "id": "evt_1a2b3c4d5e6f", "type": "payment.succeeded", "created": 1705689600, ... } ``` Your consumer should: 1. Extract `event.id` on receipt. 2. Check a persistent store (Redis, DB, idempotency table). 3. If the ID is new → process and persist the ID. 4. If the ID is known → return `2xx` without reprocessing. This is the same idempotency pattern used by the [REST API](/docs/fundamentals/idempotency) — events and API mutations share the guarantee. ## Ordering guarantees **Deliveries across different resources are not ordered.** `subscription.renewed` and the matching `invoice.paid` may arrive in either order, seconds apart. **Deliveries for the same resource are mostly ordered** — e.g., `subscription.created` before `subscription.updated` — but do not rely on strict ordering for correctness. Always reconcile against the current resource state via a GET before acting on stale assumptions. ## Dashboard tools The endpoint detail page exposes: - **Deliveries tab** — every attempt with request + response bodies, timing, and status. - **Retry button** — manually re-fire a dead delivery after you fix your consumer. - **Replay** — resend any past event to your current endpoint without affecting production traffic. ## Monitoring your endpoint - **Alert on dead deliveries** via the `endpoint.delivery.failed` event type or dashboard webhooks. - **Alert on elevated retry rates** — if more than 1% of deliveries are retrying, something is wrong. - **Track p99 response time** — if you consistently take >5 seconds, queue async and return `2xx` immediately. ## See also - **Verify signatures** (/docs/webhooks/signing): HMAC verification before acting on an event. - **Event catalogue** (/docs/webhooks/events): Every event type RevKeen emits. - **Idempotency** (/docs/fundamentals/idempotency): Same semantics as the REST API. --- # Verify signatures Source: https://docs.revkeen.com/docs/webhooks/signing HMAC signature verification, timestamp tolerance, and replay-attack prevention Every webhook request from RevKeen carries an `X-RevKeen-Signature` header. Reject any request that fails signature verification — no exceptions. ## The header ```http X-RevKeen-Signature: t=1705689600,v1=5d2c67a1b4e8f0d3c6a2b9e0f1d8c7b4a9e3f2c5d8b1a4e7f0c3b6a9d2e5f8c1 ``` | Component | Meaning | |-----------|---------| | `t=` | Unix timestamp (seconds) when RevKeen signed the request. | | `v1=` | HMAC-SHA256 of `"{t}.{payload}"` using the endpoint's signing secret. | ## Verification procedure 1. **Split the header** on `,` and parse the `t=` and `v1=` components. 2. **Compute the expected signature**: `HMAC_SHA256(secret, f"{t}.{raw_body}")` — hex-encoded. 3. **Use a constant-time compare** to match the expected and received signatures. 4. **Reject if the timestamp is more than 5 minutes old** — prevents replay attacks. 5. **Only then** parse the body and act on the event. ## SDK helpers Every official SDK ships a `webhooks.verify()` helper that does all of the above in one call. Prefer it over writing your own. ```bash # Extract components from X-RevKeen-Signature header TIMESTAMP=$(echo "$SIGHDR" | grep -oE 't=[0-9]+' | cut -d= -f2) SIGNATURE=$(echo "$SIGHDR" | grep -oE 'v1=[a-f0-9]+' | cut -d= -f2) # Compute expected EXPECTED=$(printf '%s.%s' "$TIMESTAMP" "$RAW_BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}') # Constant-time compare (bash has no native one — use a proper lib in prod) [ "$EXPECTED" = "$SIGNATURE" ] || exit 1 ``` ```ts const client = new RevKeen({ apiKey: process.env.REVKEEN_API_KEY! }); // In your webhook handler (Next.js App Router, Hono, Express, etc.) const rawBody = await request.text(); // Must be the raw string, not JSON.parse'd const signature = request.headers.get("x-revkeen-signature"); const secret = process.env.REVKEEN_WEBHOOK_SECRET!; try { const event = client.webhooks.verify(rawBody, signature!, secret); // event.type, event.data.object are now trusted } catch (err) { return new Response("invalid signature", { status: 400 }); } ``` ```go "io" "net/http" revkeen "github.com/RevKeen/sdk-go" ) func webhookHandler(w http.ResponseWriter, r *http.Request) { body, _ := io.ReadAll(r.Body) sig := r.Header.Get("X-RevKeen-Signature") event, err := revkeen.Webhooks.Verify(body, sig, os.Getenv("REVKEEN_WEBHOOK_SECRET")) if err != nil { http.Error(w, "invalid signature", http.StatusBadRequest) return } // event.Type, event.Data.Object are now trusted } ``` ```php use RevKeen\Webhooks\WebhookVerifier; $rawBody = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_REVKEEN_SIGNATURE'] ?? ''; $secret = getenv('REVKEEN_WEBHOOK_SECRET'); try { $event = WebhookVerifier::verify($rawBody, $signature, $secret); // $event->type, $event->data->object are now trusted } catch (\RevKeen\Exception\SignatureException $e) { http_response_code(400); exit('invalid signature'); } ``` ## Replay protection The timestamp `t` in the signature header is part of the signed payload. Reject deliveries where `now - t > 300s` (5 minutes). An attacker who captures a valid request cannot replay it after the window expires. ## Rotating the signing secret - Create a new endpoint with the dashboard or API — each endpoint has its own secret. - Ship the new endpoint's secret to your consumer. - Delete the old endpoint. - Alternatively, [rotate the existing endpoint's secret](/docs/api-reference) — the response returns a new secret; update your consumer before the old secret is invalidated. > **Note:** Never commit signing secrets to source control. Load them from your secrets manager (Vercel env, Infisical, AWS Secrets Manager, etc.). ## Common failure modes | Symptom | Cause | |---------|-------| | Signature always fails | Reading the request body as JSON before computing HMAC mutates whitespace. Always hash the **raw** body bytes. | | Signature fails intermittently | Clock skew between RevKeen and your server. Check NTP. | | Signature fails in production only | Reverse proxy or WAF is re-encoding the body. Pass raw bytes through. | | "signature too old" | Retry delay pushed the request past the 5-minute window. Retries carry a **fresh** timestamp and signature; only delivered-now requests should verify. | ## See also - **Retry behavior** (/docs/webhooks/retry-behavior): How RevKeen retries failed deliveries. - **Event catalogue** (/docs/webhooks/events): Every event type + payload. - **Idempotency** (/docs/fundamentals/idempotency): Deduplicate events by `id`. --- # API Reference Source: https://docs.revkeen.com/docs/api-reference Complete REST API reference for the RevKeen billing and payments platform The RevKeen API is organized around REST. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ## Base URL ``` https://api.revkeen.com/v2 ``` Use `https://staging-api.revkeen.com/v2` for test mode. No real charges are created in test mode. ## Authentication All API requests require authentication via the `x-api-key` header: ```bash curl https://api.revkeen.com/v2/invoices \ -H "x-api-key: rk_live_..." ``` | Environment | Key prefix | Description | |---|---|---| | Test mode | `rk_sandbox_` | No real charges. Safe for development. | | Live mode | `rk_live_` | Real transactions. Use in production. | Get your API keys from [Dashboard > Settings > API Keys](https://app.revkeen.com/settings/api-keys). See [Authentication](/docs/fundamentals/authentication) for OAuth 2.1 and scoped keys. ## Rate limits | Environment | Requests / min | Burst | |---|---|---| | Test mode | 100 | 200 | | Production | 1,000 | 2,000 | | Enterprise | Custom | Custom | Rate-limited responses return `429 Too Many Requests` with a `Retry-After` header. See [Rate Limits](/docs/fundamentals/rate-limits). ## Idempotency All `POST` endpoints accept an `Idempotency-Key` header (UUID v4 recommended). Keys are valid for 24 hours. Duplicate requests within the TTL return the original response. See [Idempotency](/docs/fundamentals/idempotency). ## Versioning The API is versioned by date. Pin a version via the `RevKeen-Version` header: ``` RevKeen-Version: 2026-05-01 ``` --- ## Browse by category --- ## Customers Create and manage customers, their payment methods, entitlements, and portal sessions. --- ## Products & Pricing Manage your product catalogue, pricing tiers, and discounts. --- ## Invoices & Credit Notes Create, send, and manage invoices. Issue credit notes for partial or full refunds. --- ## Subscriptions Create and manage recurring billing, plan changes, and billing schedules. --- ## Payments Process one-time payments, capture authorized charges, and manage refunds and voids. --- ## Checkout Create payment links and hosted checkout sessions for your customers. --- ## Usage Billing Ingest usage events, define meters, and bill customers based on consumption. --- ## Orders Create, pay for, and fulfil orders. --- ## Transactions & Payouts View transactions, disputes, and settlement payouts across all payment activity. --- ## Terminal Initiate and manage in-person payments through connected terminal devices. --- ## Analytics & Finance Access revenue metrics, customer analytics, checkout funnels, and financial reports. --- ## Webhooks & Events Subscribe to real-time event notifications and manage webhook endpoints. --- ## Automations Create and manage automated workflows with approval gates. --- ## Integrations Connect RevKeen with external systems, manage sync state, and configure provider mappings. --- ## Data Management Import and export data in bulk. --- # List Abandonment Alerts Source: https://docs.revkeen.com/docs/api-reference/analytics_checkout_abandonment_list **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Get paginated list of abandonment alerts with filtering --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Abandonment Alert Summary Source: https://docs.revkeen.com/docs/api-reference/analytics_checkout_abandonment_summary **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics --- Get aggregated abandonment alert metrics by status and severity --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics --- # Checkout Funnel Analytics Source: https://docs.revkeen.com/docs/api-reference/analytics_checkout_funnel **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- Get stage-by-stage checkout conversion funnel metrics. Shows sessions, drop-offs, and conversion rates at each step. --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- # List Winback Opportunities Source: https://docs.revkeen.com/docs/api-reference/analytics_checkout_winback_list **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Get paginated list of winback opportunities with filtering --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Winback Opportunities Summary Source: https://docs.revkeen.com/docs/api-reference/analytics_checkout_winback_summary **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics --- Get aggregated winback opportunity metrics by type and status --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics --- # Days Sales Outstanding Source: https://docs.revkeen.com/docs/api-reference/analytics_collections_dso **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- Calculate DSO and collection health metrics --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- # Customer Analytics Source: https://docs.revkeen.com/docs/api-reference/analytics_customers_get **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Get analytics for a specific customer --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Customer LTV Source: https://docs.revkeen.com/docs/api-reference/analytics_customers_ltv **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- Calculate customer lifetime value metrics --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- # A/R Aging Report Source: https://docs.revkeen.com/docs/api-reference/analytics_invoices_ar_aging **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- Returns Accounts Receivable aging buckets with invoice counts and amounts --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- # Payment Link Conversion Source: https://docs.revkeen.com/docs/api-reference/analytics_payment_links_conversion **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- Get payment link performance metrics --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- # MRR Summary Source: https://docs.revkeen.com/docs/api-reference/analytics_revenue_mrr_summary **Related endpoints** - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- Get Monthly Recurring Revenue metrics and growth --- **Related endpoints** - `GET /analytics/revenue/time-series` — Revenue Time Series - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- # Revenue Time Series Source: https://docs.revkeen.com/docs/api-reference/analytics_revenue_time_series **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- Get revenue data over time with configurable granularity --- **Related endpoints** - `GET /analytics/revenue/mrr-summary` — MRR Summary - `GET /analytics/invoices/ar-aging` — A/R Aging Report - `GET /analytics/collections/dso` — Days Sales Outstanding - `GET /analytics/customers/ltv` — Customer LTV - `GET /analytics/customers/{customerId}` — Customer Analytics - `GET /analytics/payment-links/conversion` — Payment Link Conversion - `GET /analytics/checkout/funnel` — Checkout Funnel Analytics - `GET /analytics/checkout/abandonment/summary` — Abandonment Alert Summary --- # List approvals Source: https://docs.revkeen.com/docs/api-reference/automations_approvals_list **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List pending and resolved automation approval requests. --- **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Approve an automation approval Source: https://docs.revkeen.com/docs/api-reference/automations_approve **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Approve a pending automation approval request so the run can proceed. --- **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create an automation Source: https://docs.revkeen.com/docs/api-reference/automations_create **Related endpoints** - `GET /automations` — List automations - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a saved Assistant automation definition and immutable first version. --- **Related endpoints** - `GET /automations` — List automations - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve an automation Source: https://docs.revkeen.com/docs/api-reference/automations_get **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Get a saved automation and its current version details. --- **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List automations Source: https://docs.revkeen.com/docs/api-reference/automations_list **Related endpoints** - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List saved Assistant automations for the authenticated merchant. --- **Related endpoints** - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Reject an automation approval Source: https://docs.revkeen.com/docs/api-reference/automations_reject **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Reject a pending automation approval request, optionally providing a reason. --- **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Run an automation Source: https://docs.revkeen.com/docs/api-reference/automations_run **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Queue a manual run of a saved automation. --- **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve a run Source: https://docs.revkeen.com/docs/api-reference/automations_runs_get **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Get the details of a specific automation run including its steps and outputs. --- **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `GET /automations/{id}/runs` — List runs for an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List runs for an automation Source: https://docs.revkeen.com/docs/api-reference/automations_runs_list **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List execution runs for a saved automation, optionally filtered by status. --- **Related endpoints** - `GET /automations` — List automations - `POST /automations` — Create an automation - `GET /automations/{id}` — Retrieve an automation - `POST /automations/{id}/runs` — Run an automation - `GET /automations/{id}/runs/{runId}` — Retrieve a run - `GET /automations/approvals` — List approvals - `POST /automations/approvals/{approvalId}/approve` — Approve an automation approval - `POST /automations/approvals/{approvalId}/reject` — Reject an automation approval **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Get billing anchor rules Source: https://docs.revkeen.com/docs/api-reference/billing_anchor_rules_list **Related endpoints** - `POST /billing/preview` — Generate billing schedule preview - `GET /billing/intervals` — Get billing intervals **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Get the list of supported billing anchor rules with explanations. --- **Related endpoints** - `POST /billing/preview` — Generate billing schedule preview - `GET /billing/intervals` — Get billing intervals **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Get billing intervals Source: https://docs.revkeen.com/docs/api-reference/billing_intervals_list **Related endpoints** - `POST /billing/preview` — Generate billing schedule preview - `GET /billing/anchor-rules` — Get billing anchor rules **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Get the list of supported billing intervals and their display labels. --- **Related endpoints** - `POST /billing/preview` — Generate billing schedule preview - `GET /billing/anchor-rules` — Get billing anchor rules **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Generate billing schedule preview Source: https://docs.revkeen.com/docs/api-reference/billing_preview_create **Related endpoints** - `GET /billing/intervals` — Get billing intervals - `GET /billing/anchor-rules` — Get billing anchor rules **Common errors** - `400 invalid_request` — malformed payload or failed validation. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Generate a preview of upcoming billing dates and amounts based on the provided schedule configuration. This endpoint uses the same billing calculation logic as the actual scheduler, ensuring that the preview matches what will actually be billed (Key Invariant #4: Preview === Scheduler). Use this to show customers their expected billing schedule before they subscribe, or to preview changes to an existing subscription's billing configuration. --- **Related endpoints** - `GET /billing/intervals` — Get billing intervals - `GET /billing/anchor-rules` — Get billing anchor rules **Common errors** - `400 invalid_request` — malformed payload or failed validation. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Capture charge Source: https://docs.revkeen.com/docs/api-reference/charges_capture **Related endpoints** - `POST /charges` — Create a one-time charge - `GET /charges` — List charges - `GET /charges/{id}` — Get charge - `POST /charges/{id}/refund` — Refund charge **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Capture a charge that was created with `capture: false`. You can capture the full amount or a partial amount. --- **Related endpoints** - `POST /charges` — Create a one-time charge - `GET /charges` — List charges - `GET /charges/{id}` — Get charge - `POST /charges/{id}/refund` — Refund charge **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a one-time charge Source: https://docs.revkeen.com/docs/api-reference/charges_create **Related endpoints** - `GET /charges` — List charges - `GET /charges/{id}` — Get charge - `POST /charges/{id}/capture` — Capture charge - `POST /charges/{id}/refund` — Refund charge **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a one-time charge for an existing customer. This is for ad-hoc charges like setup fees, overages, or one-time services. For recurring billing, use subscriptions instead. The charge will be processed immediately using the customer's default payment method, unless a specific payment method ID is provided. --- **Related endpoints** - `GET /charges` — List charges - `GET /charges/{id}` — Get charge - `POST /charges/{id}/capture` — Capture charge - `POST /charges/{id}/refund` — Refund charge **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get charge Source: https://docs.revkeen.com/docs/api-reference/charges_get **Related endpoints** - `POST /charges` — Create a one-time charge - `GET /charges` — List charges - `POST /charges/{id}/capture` — Capture charge - `POST /charges/{id}/refund` — Refund charge **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve details of a specific charge. --- **Related endpoints** - `POST /charges` — Create a one-time charge - `GET /charges` — List charges - `POST /charges/{id}/capture` — Capture charge - `POST /charges/{id}/refund` — Refund charge **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List charges Source: https://docs.revkeen.com/docs/api-reference/charges_list **Related endpoints** - `POST /charges` — Create a one-time charge - `GET /charges/{id}` — Get charge - `POST /charges/{id}/capture` — Capture charge - `POST /charges/{id}/refund` — Refund charge **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve a paginated list of charges with optional filtering by customer, status, or date range. --- **Related endpoints** - `POST /charges` — Create a one-time charge - `GET /charges/{id}` — Get charge - `POST /charges/{id}/capture` — Capture charge - `POST /charges/{id}/refund` — Refund charge **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Refund charge Source: https://docs.revkeen.com/docs/api-reference/charges_refund **Related endpoints** - `POST /charges` — Create a one-time charge - `GET /charges` — List charges - `GET /charges/{id}` — Get charge - `POST /charges/{id}/capture` — Capture charge **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Refund a charge. You can refund the full amount or specify a partial refund amount. Multiple partial refunds can be issued until the full amount is refunded. --- **Related endpoints** - `POST /charges` — Create a one-time charge - `GET /charges` — List charges - `GET /charges/{id}` — Get charge - `POST /charges/{id}/capture` — Capture charge **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a checkout session Source: https://docs.revkeen.com/docs/api-reference/checkout_sessions_create **Related endpoints** - `GET /checkout-sessions/{id}` — Retrieve a checkout session - `POST /checkout-sessions/{id}/expire` — Expire a checkout session **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a checkout session for an invoice or product. --- **Related endpoints** - `GET /checkout-sessions/{id}` — Retrieve a checkout session - `POST /checkout-sessions/{id}/expire` — Expire a checkout session **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Expire a checkout session Source: https://docs.revkeen.com/docs/api-reference/checkout_sessions_expire **Related endpoints** - `POST /checkout-sessions` — Create a checkout session - `GET /checkout-sessions/{id}` — Retrieve a checkout session **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Manually expire an open checkout session. Only sessions with status 'open' or 'pending' and no active payment attempt can be expired. --- **Related endpoints** - `POST /checkout-sessions` — Create a checkout session - `GET /checkout-sessions/{id}` — Retrieve a checkout session **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve a checkout session Source: https://docs.revkeen.com/docs/api-reference/checkout_sessions_get **Related endpoints** - `POST /checkout-sessions` — Create a checkout session - `POST /checkout-sessions/{id}/expire` — Expire a checkout session **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve a checkout session by its ID. --- **Related endpoints** - `POST /checkout-sessions` — Create a checkout session - `POST /checkout-sessions/{id}/expire` — Expire a checkout session **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List messages in a thread Source: https://docs.revkeen.com/docs/api-reference/comms_messages_list **Related endpoints** - `POST /comms/send` — Send a message - `GET /comms/threads` — List conversation threads **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List all messages in a conversation thread --- **Related endpoints** - `POST /comms/send` — Send a message - `GET /comms/threads` — List conversation threads **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Send a message Source: https://docs.revkeen.com/docs/api-reference/comms_messages_send **Related endpoints** - `GET /comms/threads` — List conversation threads - `GET /comms/threads/{threadId}/messages` — List messages in a thread **Common errors** - `400 invalid_request` — malformed payload or failed validation. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Send a direct message to a customer via email, SMS, or WhatsApp --- **Related endpoints** - `GET /comms/threads` — List conversation threads - `GET /comms/threads/{threadId}/messages` — List messages in a thread **Common errors** - `400 invalid_request` — malformed payload or failed validation. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # List conversation threads Source: https://docs.revkeen.com/docs/api-reference/comms_threads_list **Related endpoints** - `POST /comms/send` — Send a message - `GET /comms/threads/{threadId}/messages` — List messages in a thread **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List conversation threads for the authenticated merchant --- **Related endpoints** - `POST /comms/send` — Send a message - `GET /comms/threads/{threadId}/messages` — List messages in a thread **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Create a credit note Source: https://docs.revkeen.com/docs/api-reference/credit_notes_create **Related endpoints** - `GET /credit_notes` — List credit notes - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Issue a credit note for a paid or partially paid invoice. The credit can be applied via refund to payment method, customer balance, or marked as external. --- **Related endpoints** - `GET /credit_notes` — List credit notes - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get credit note by ID Source: https://docs.revkeen.com/docs/api-reference/credit_notes_get **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve a single credit note by its UUID. --- **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Check credit note eligibility for an invoice Source: https://docs.revkeen.com/docs/api-reference/credit_notes_invoice_eligibility **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Returns per-payment breakdown of available reversal operations across all gateways. Use this before creating a credit note to understand what reversal methods are available. --- **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List credit notes Source: https://docs.revkeen.com/docs/api-reference/credit_notes_list **Related endpoints** - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve a paginated list of credit notes with optional filters. Results are ordered by creation date (newest first). --- **Related endpoints** - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # List line items on a credit note Source: https://docs.revkeen.com/docs/api-reference/credit_notes_list_lines **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Returns the line items attached to a credit note. Each line describes a portion of the invoice that the credit applies to — either a whole invoice line or a prorated slice. Use this to reconstruct the credit's effect per invoice line (for example, when displaying the credit breakdown in your own UI). --- **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Preview a credit note without creating it Source: https://docs.revkeen.com/docs/api-reference/credit_notes_preview **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Compute what a credit note would look like against a specific invoice without persisting anything. Use this to validate amounts and show a "here's what will happen" UI before the merchant commits. No side effects — no DB writes, no events emitted, no refunds initiated. Mirrors Stripe's `POST /v1/credit_notes/preview`. --- **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Check reversal eligibility for a transaction Source: https://docs.revkeen.com/docs/api-reference/credit_notes_transaction_reversal_eligibility **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Returns available reversal operations for a specific payment transaction, including terminal-specific options and NMI fallback paths. For terminal (card-present) transactions, pass `customer_present=true` to see terminal-native operations. --- **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `POST /credit_notes/{id}/void` — Void a credit note - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Void a credit note Source: https://docs.revkeen.com/docs/api-reference/credit_notes_void **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Void a credit note that has been issued but not yet fully applied. This is an accounting void — it reverses the credit without creating a new financial transaction. --- **Related endpoints** - `GET /credit_notes` — List credit notes - `POST /credit_notes` — Create a credit note - `GET /credit_notes/{id}` — Get credit note by ID - `GET /credit_notes/invoice/{invoice_id}/eligibility` — Check credit note eligibility for an invoice - `GET /credit_notes/transaction/{transaction_id}/reversal-eligibility` — Check reversal eligibility for a transaction - `GET /credit_notes/{id}/lines` — List line items on a credit note - `POST /credit_notes/preview` — Preview a credit note without creating it **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve a customer-meter aggregate Source: https://docs.revkeen.com/docs/api-reference/customer_meters_get **Related endpoints** - `GET /customer-meters` — List a customer's meter usage **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Returns a single customer-meter aggregate for the specified customer + meter pair. Returns 404 only if the meter itself does not exist on the merchant — if the meter exists but the customer has zero events, the response returns an aggregate with `total_quantity: 0`, `event_count: 0`, `last_event_at: null`. --- **Related endpoints** - `GET /customer-meters` — List a customer's meter usage **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List a customer's meter usage Source: https://docs.revkeen.com/docs/api-reference/customer_meters_list **Related endpoints** - `GET /customer-meters/{customer_id}/{meter_id}` — Retrieve a customer-meter aggregate **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Returns per-meter aggregates for a single customer. Requires a `customer_id` query parameter. For each meter the merchant has defined, the response includes the aggregate quantity (applying the meter's native aggregation function), the event count, and the most recent event timestamp. Use this to render a customer's current consumption snapshot in your own UI — for example, a usage dashboard showing "4,820 / 10,000 requests this period". --- **Related endpoints** - `GET /customer-meters/{customer_id}/{meter_id}` — Retrieve a customer-meter aggregate **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Retrieve the authenticated customer Source: https://docs.revkeen.com/docs/api-reference/customer_portal_customer_get **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Returns the customer represented by the bearer token. Useful as a warm-up / identity check when an embedded portal page loads. --- **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Retrieve an invoice Source: https://docs.revkeen.com/docs/api-reference/customer_portal_invoices_get **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Returns an invoice owned by the authenticated customer. --- **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List the authenticated customer's invoices Source: https://docs.revkeen.com/docs/api-reference/customer_portal_invoices_list **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Returns invoices owned by the authenticated customer, reverse-chronological by `invoice_date`. Use the same `starting_after`/`ending_before` cursor pattern as subscriptions. --- **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Create a customer-portal session Source: https://docs.revkeen.com/docs/api-reference/customer_portal_sessions_create **Related endpoints** - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Mint a short-lived bearer token that authenticates a specific customer against /v2/customer-portal/*. Returns an opaque `rkcps_...` token that expires in 60 minutes by default. Call this server-side from the merchant's backend, then hand the token to the customer's browser or embedded client. Treat the token like a password — never log it and never expose it to untrusted code. --- **Related endpoints** - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Cancel a subscription Source: https://docs.revkeen.com/docs/api-reference/customer_portal_subscriptions_cancel **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Cancel a subscription owned by the authenticated customer. By default the subscription is scheduled to cancel at the end of the current billing period — set `cancel_at_period_end=false` to cancel immediately. Idempotent — cancelling an already-canceled subscription is a no-op that returns the current state. --- **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve a subscription Source: https://docs.revkeen.com/docs/api-reference/customer_portal_subscriptions_get **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Returns a subscription owned by the authenticated customer. 404s on cross-customer access even if the subscription exists. --- **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions` — List the authenticated customer's subscriptions - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List the authenticated customer's subscriptions Source: https://docs.revkeen.com/docs/api-reference/customer_portal_subscriptions_list **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Returns subscriptions where the customer is the subscriber. Results are reverse-chronological by creation time and paginate via `starting_after` / `ending_before` cursors. --- **Related endpoints** - `POST /customer-portal/sessions` — Create a customer-portal session - `GET /customer-portal/customer` — Retrieve the authenticated customer - `GET /customer-portal/subscriptions/{id}` — Retrieve a subscription - `POST /customer-portal/subscriptions/{id}/cancel` — Cancel a subscription - `GET /customer-portal/invoices` — List the authenticated customer's invoices - `GET /customer-portal/invoices/{id}` — Retrieve an invoice **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Create a new customer Source: https://docs.revkeen.com/docs/api-reference/customers_create **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a new customer record in the merchant's account --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Check customer entitlement Source: https://docs.revkeen.com/docs/api-reference/customers_entitlements_check **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements` — List entitlements - `GET /entitlements/check` — Check entitlement access **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Check if a customer has access to a specific benefit by key. This is the primary endpoint for feature gating and licensing checks. --- **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements` — List entitlements - `GET /entitlements/check` — Check entitlement access **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Grant entitlement to customer Source: https://docs.revkeen.com/docs/api-reference/customers_entitlements_grant **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements` — List entitlements - `GET /entitlements/check` — Check entitlement access **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Grant a benefit/entitlement to a customer. Provide either benefitId or benefitKey to identify the benefit. Emits an entitlement.granted webhook event. --- **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements` — List entitlements - `GET /entitlements/check` — Check entitlement access **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # List customer entitlements Source: https://docs.revkeen.com/docs/api-reference/customers_entitlements_list **Related endpoints** - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements` — List entitlements - `GET /entitlements/check` — Check entitlement access **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve all entitlements (benefits/features) for a specific customer. Includes computed access status based on subscription state. --- **Related endpoints** - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements` — List entitlements - `GET /entitlements/check` — Check entitlement access **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Revoke entitlement by ID Source: https://docs.revkeen.com/docs/api-reference/customers_entitlements_revoke_by_id **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `GET /entitlements` — List entitlements - `GET /entitlements/check` — Check entitlement access **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Revoke a specific entitlement from a customer by entitlement ID. Emits an entitlement.revoked webhook event. --- **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `GET /entitlements` — List entitlements - `GET /entitlements/check` — Check entitlement access **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Revoke entitlement by benefit key Source: https://docs.revkeen.com/docs/api-reference/customers_entitlements_revoke_by_key **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements` — List entitlements - `GET /entitlements/check` — Check entitlement access **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Revoke an entitlement from a customer by benefit key. Provide benefitKey as a query parameter. Emits an entitlement.revoked webhook event. --- **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements` — List entitlements - `GET /entitlements/check` — Check entitlement access **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Batch upsert customers by external ID Source: https://docs.revkeen.com/docs/api-reference/customers_external_batch **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create or update multiple customers by external system ID. Supports up to 100 customers per request with stale update protection. --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Upsert customer by external ID Source: https://docs.revkeen.com/docs/api-reference/customers_external_upsert_by_external_id **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create or update a customer identified by external source and ID. Used by integrations (PracticeHub, Wodify) to sync customers. --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get customer by ID Source: https://docs.revkeen.com/docs/api-reference/customers_get **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve detailed information about a specific customer --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List customer invoices Source: https://docs.revkeen.com/docs/api-reference/customers_invoices_list **Related endpoints** - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve all invoices for a specific customer --- **Related endpoints** - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # List customers Source: https://docs.revkeen.com/docs/api-reference/customers_list **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve a paginated list of customers for the merchant --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # List customer orders Source: https://docs.revkeen.com/docs/api-reference/customers_orders_list **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve all orders for a specific customer --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Get customer payment methods Source: https://docs.revkeen.com/docs/api-reference/customers_payment_methods_list **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve all payment methods for a customer --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # List customer payments Source: https://docs.revkeen.com/docs/api-reference/customers_payments_list **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve all payments for a specific customer --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Create a customer portal session Source: https://docs.revkeen.com/docs/api-reference/customers_portal_sessions_create **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a temporary portal session URL for a customer. The customer can use this URL to access their portal without requiring them to sign in with a magic link. --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # List customer subscriptions Source: https://docs.revkeen.com/docs/api-reference/customers_subscriptions_list **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve all subscriptions for a specific customer --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID - `PATCH /customers/{id}` — Update customer details **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Update customer details Source: https://docs.revkeen.com/docs/api-reference/customers_update **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update an existing customer's information --- **Related endpoints** - `GET /customers/{customerId}/invoices` — List customer invoices - `GET /customers/{customerId}/subscriptions` — List customer subscriptions - `GET /customers/{customerId}/orders` — List customer orders - `GET /customers/{customerId}/payments` — List customer payments - `PUT /customers/external/batch` — Batch upsert customers by external ID - `POST /customers` — Create a new customer - `GET /customers` — List customers - `GET /customers/{id}` — Get customer by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a discount Source: https://docs.revkeen.com/docs/api-reference/discounts_create **Related endpoints** - `GET /discounts` — List discounts - `GET /discounts/{id}` — Get discount by ID - `PATCH /discounts/{id}` — Update a discount - `DELETE /discounts/{id}` — Delete a discount **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a new discount code. --- **Related endpoints** - `GET /discounts` — List discounts - `GET /discounts/{id}` — Get discount by ID - `PATCH /discounts/{id}` — Update a discount - `DELETE /discounts/{id}` — Delete a discount **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Delete a discount Source: https://docs.revkeen.com/docs/api-reference/discounts_delete **Related endpoints** - `GET /discounts` — List discounts - `POST /discounts` — Create a discount - `GET /discounts/{id}` — Get discount by ID - `PATCH /discounts/{id}` — Update a discount **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Archive a discount (soft delete). The discount code can no longer be used. --- **Related endpoints** - `GET /discounts` — List discounts - `POST /discounts` — Create a discount - `GET /discounts/{id}` — Get discount by ID - `PATCH /discounts/{id}` — Update a discount **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get discount by ID Source: https://docs.revkeen.com/docs/api-reference/discounts_get **Related endpoints** - `GET /discounts` — List discounts - `POST /discounts` — Create a discount - `PATCH /discounts/{id}` — Update a discount - `DELETE /discounts/{id}` — Delete a discount **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve a single discount by its ID. --- **Related endpoints** - `GET /discounts` — List discounts - `POST /discounts` — Create a discount - `PATCH /discounts/{id}` — Update a discount - `DELETE /discounts/{id}` — Delete a discount **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List discounts Source: https://docs.revkeen.com/docs/api-reference/discounts_list **Related endpoints** - `POST /discounts` — Create a discount - `GET /discounts/{id}` — Get discount by ID - `PATCH /discounts/{id}` — Update a discount - `DELETE /discounts/{id}` — Delete a discount **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve a paginated list of discounts. --- **Related endpoints** - `POST /discounts` — Create a discount - `GET /discounts/{id}` — Get discount by ID - `PATCH /discounts/{id}` — Update a discount - `DELETE /discounts/{id}` — Delete a discount **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Update a discount Source: https://docs.revkeen.com/docs/api-reference/discounts_update **Related endpoints** - `GET /discounts` — List discounts - `POST /discounts` — Create a discount - `GET /discounts/{id}` — Get discount by ID - `DELETE /discounts/{id}` — Delete a discount **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update an existing discount. Note: discount code and type cannot be changed. --- **Related endpoints** - `GET /discounts` — List discounts - `POST /discounts` — Create a discount - `GET /discounts/{id}` — Get discount by ID - `DELETE /discounts/{id}` — Delete a discount **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get dispute by ID Source: https://docs.revkeen.com/docs/api-reference/disputes_get **Related endpoints** - `GET /disputes` — List disputes - `GET /disputes/open` — Get open disputes requiring action **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve a single dispute by its public ID (dsp_xxx) or internal UUID. --- **Related endpoints** - `GET /disputes` — List disputes - `GET /disputes/open` — Get open disputes requiring action **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Get open disputes requiring action Source: https://docs.revkeen.com/docs/api-reference/disputes_get_open **Related endpoints** - `GET /disputes` — List disputes - `GET /disputes/{id}` — Get dispute by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve disputes that need evidence submission, ordered by due date (most urgent first). Use this to prioritize dispute responses. --- **Related endpoints** - `GET /disputes` — List disputes - `GET /disputes/{id}` — Get dispute by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # List disputes Source: https://docs.revkeen.com/docs/api-reference/disputes_list **Related endpoints** - `GET /disputes/open` — Get open disputes requiring action - `GET /disputes/{id}` — Get dispute by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve a paginated list of disputes/chargebacks with optional filters. Results are ordered by disputed date (newest first). --- **Related endpoints** - `GET /disputes/open` — Get open disputes requiring action - `GET /disputes/{id}` — Get dispute by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Check entitlement access Source: https://docs.revkeen.com/docs/api-reference/entitlements_check **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements` — List entitlements **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Check if a customer has access to a specific benefit by key. This is the primary endpoint for feature gating and licensing checks. --- **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements` — List entitlements **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List entitlements Source: https://docs.revkeen.com/docs/api-reference/entitlements_list **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements/check` — Check entitlement access **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve all entitlements for a customer. Pass `customer_id` as a query parameter. Includes computed access status based on subscription state. --- **Related endpoints** - `GET /customers/{customerId}/entitlements` — List customer entitlements - `POST /customers/{customerId}/entitlements` — Grant entitlement to customer - `DELETE /customers/{customerId}/entitlements` — Revoke entitlement by benefit key - `GET /customers/{customerId}/entitlements/check` — Check customer entitlement - `DELETE /customers/{customerId}/entitlements/{entitlementId}` — Revoke entitlement by ID - `GET /entitlements/check` — Check entitlement access **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Create a test event Source: https://docs.revkeen.com/docs/api-reference/events_create_test **Related endpoints** - `GET /events` — List events - `GET /events/{id}` — Retrieve an event - `POST /events/{id}/resend` — Resend webhook for an event **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Creates a simulated test event that triggers webhook delivery to configured endpoints. Useful for testing webhook integrations. --- **Related endpoints** - `GET /events` — List events - `GET /events/{id}` — Retrieve an event - `POST /events/{id}/resend` — Resend webhook for an event **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve an event Source: https://docs.revkeen.com/docs/api-reference/events_get **Related endpoints** - `GET /events` — List events - `POST /events/{id}/resend` — Resend webhook for an event - `POST /events/test` — Create a test event **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieves the details of an event by its ID. --- **Related endpoints** - `GET /events` — List events - `POST /events/{id}/resend` — Resend webhook for an event - `POST /events/test` — Create a test event **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List events Source: https://docs.revkeen.com/docs/api-reference/events_list **Related endpoints** - `GET /events/{id}` — Retrieve an event - `POST /events/{id}/resend` — Resend webhook for an event - `POST /events/test` — Create a test event **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Returns a list of events with optional filters. Events are returned in reverse chronological order. --- **Related endpoints** - `GET /events/{id}` — Retrieve an event - `POST /events/{id}/resend` — Resend webhook for an event - `POST /events/test` — Create a test event **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Resend webhook for an event Source: https://docs.revkeen.com/docs/api-reference/events_resend **Related endpoints** - `GET /events` — List events - `GET /events/{id}` — Retrieve an event - `POST /events/test` — Create a test event **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Queues the event to be resent to all configured webhook endpoints. --- **Related endpoints** - `GET /events` — List events - `GET /events/{id}` — Retrieve an event - `POST /events/test` — Create a test event **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create an export Source: https://docs.revkeen.com/docs/api-reference/exports_create **Related endpoints** - `GET /exports/{id}` — Get export status **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create an async data export. The export is processed in the background. Poll `GET /v2/exports/:id` for status and download URL. --- **Related endpoints** - `GET /exports/{id}` — Get export status **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get export status Source: https://docs.revkeen.com/docs/api-reference/exports_get **Related endpoints** - `POST /exports` — Create an export **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Check the status of an export job. When status is 'completed', the download_url will contain a presigned URL (valid for 1 hour). --- **Related endpoints** - `POST /exports` — Create an export **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Get income report Source: https://docs.revkeen.com/docs/api-reference/finance_income **Related endpoints** - `GET /finance/summary` — Get finance summary **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Get income report for the authenticated merchant. Requires 'finance:read' scope. --- **Related endpoints** - `GET /finance/summary` — Get finance summary **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Get finance summary Source: https://docs.revkeen.com/docs/api-reference/finance_summary **Related endpoints** - `GET /finance/income` — Get income report **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Get finance summary for the authenticated merchant. Requires 'finance:read' scope. --- **Related endpoints** - `GET /finance/income` — Get income report **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Create an import Source: https://docs.revkeen.com/docs/api-reference/imports_create **Related endpoints** - `GET /imports/{id}` — Get import status **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a bulk data import job. The import is processed asynchronously. Poll `GET /v2/imports/:id` for progress and errors. --- **Related endpoints** - `GET /imports/{id}` — Get import status **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get import status Source: https://docs.revkeen.com/docs/api-reference/imports_get **Related endpoints** - `POST /imports` — Create an import **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Check the status and progress of an import job. Includes detailed error information for failed rows. --- **Related endpoints** - `POST /imports` — Create an import **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Activate integration Source: https://docs.revkeen.com/docs/api-reference/integrations_activate **Related endpoints** - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Activate an external integration for the authenticated merchant. Validates the supplied credentials against the provider, stores them via KMS envelope encryption, seeds the sync-state cursor, and schedules the first incremental sync. Returns `409` if the merchant already has an active integration with this provider — call the deactivate endpoint first, or use `/sync-toggle` to resume a paused integration. --- **Related endpoints** - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Toggle auto-send invoices Source: https://docs.revkeen.com/docs/api-reference/integrations_auto_send_invoices_update **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- When enabled, invoices synced from the external provider are automatically emailed to the customer on arrival using the merchant's default email template. When disabled, synced invoices land in `draft` state and must be finalised manually. Existing invoices are unaffected by this toggle. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Batch retry sync logs Source: https://docs.revkeen.com/docs/api-reference/integrations_batch_retry **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Re-enqueue all retryable failed entries for an integration in one call. Emits one retry attempt per entry; respects the integration's circuit breaker (capped at `max_consecutive_errors`). Returns a summary of how many were queued versus skipped. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get billable items from line items Source: https://docs.revkeen.com/docs/api-reference/integrations_billable_items_list **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Fetch every distinct `billable_item_id` observed on the provider's invoice line items over the lookback window, regardless of package membership. Reveals billable items that exist on invoices but are missing from packages — a common drift case when the provider allows ad-hoc invoice lines. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Deactivate integration Source: https://docs.revkeen.com/docs/api-reference/integrations_deactivate **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Deactivate an active integration. Cancels in-flight sync jobs, clears scheduled cron entries, and purges stored credentials via KMS. Historical sync logs, product mappings, and payment-method mappings are retained so re-activation preserves the mapping set. Returns `404` if no active integration exists for the provider. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get integration status Source: https://docs.revkeen.com/docs/api-reference/integrations_get_status **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. --- Return the current configuration snapshot for a provider — activation state, last sync timestamp, next scheduled sync, sync interval, auto-send setting, invoice lookback window, and circuit-breaker error count. Does not trigger a sync or a credential test; use `/sync` or `/test` for those. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. --- # Update invoice lookback period Source: https://docs.revkeen.com/docs/api-reference/integrations_invoice_lookback_update **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Set how many days of historical invoices are fetched on the first (full) sync. Applies only to the initial bootstrap — subsequent incremental syncs use the per-resource cursor regardless of this value. Typical range 30–365 days. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # List all integrations Source: https://docs.revkeen.com/docs/api-reference/integrations_list **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Return every integration configured for the authenticated merchant, active or not. Used by the integrations dashboard to render the connection grid. Each entry includes activation state, last sync timestamp, and the provider's display metadata. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Get external packages Source: https://docs.revkeen.com/docs/api-reference/integrations_packages_list **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Fetch the list of packages (or equivalent product / service records) from the external provider using stored credentials. Used by the product-mapping UI to populate the left-hand column. Passes through pagination and filtering headers when the provider supports them. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Update payment mappings Source: https://docs.revkeen.com/docs/api-reference/integrations_payment_mappings_update **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Replace the full set of payment-method mappings between RevKeen's internal payment methods and the external provider's payment modes. Used to control how reconciled payments are tagged on the provider side. The mapping set is applied atomically — partial updates are not supported. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get external payment methods (stored credentials) Source: https://docs.revkeen.com/docs/api-reference/integrations_payment_methods_list **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Fetch the live list of payment methods configured on the external provider, using the merchant's stored credentials. Used by the mappings UI to populate the provider-side dropdown. Credentials must already be stored — call the `POST` variant for credential-less lookups during the activation wizard. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Get external payment methods (temporary credentials) Source: https://docs.revkeen.com/docs/api-reference/integrations_payment_methods_lookup **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Fetch payment methods using one-shot credentials supplied in the request body. Used by the activation wizard before credentials are stored, so the merchant can preview the mappings they'll need to configure. Credentials are not persisted by this call. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Delete product mapping Source: https://docs.revkeen.com/docs/api-reference/integrations_product_mappings_delete **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Delete a single product mapping by its external package ID. Any future syncs that reference this external package will be reported as unmapped until a new mapping is created. Returns `404` if no mapping exists for the supplied external ID. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get product mappings Source: https://docs.revkeen.com/docs/api-reference/integrations_product_mappings_list **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Return the current mapping set between external packages and RevKeen products. Ordered by external package ID; includes the RevKeen product the package maps to (nullable when unmapped) and an optional price override. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Save product mappings Source: https://docs.revkeen.com/docs/api-reference/integrations_product_mappings_update **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Replace the full product-mapping set atomically. The request body is treated as the desired end state — any existing mapping not in the payload is deleted. To change a single mapping without affecting others, read first via `GET` then send the merged set back. Use `DELETE` for single-mapping removal. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Resume sync after auto-pause Source: https://docs.revkeen.com/docs/api-reference/integrations_resume_sync **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Reset the integration's circuit breaker (consecutive-error counter) and enqueue an immediate sync run. Use after fixing provider-side issues that caused the auto-pause. Equivalent to a status update followed by `/sync`, but captured as a single atomic operation for audit purposes. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retry sync log Source: https://docs.revkeen.com/docs/api-reference/integrations_retry_log **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Re-enqueue a single failed sync log entry for another attempt. The underlying retry uses the same idempotency key so successful records are not duplicated. Returns `400` if the entry is not in a retryable state (permanent failure, already succeeded, or the target resource has since been deleted). --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # AI-suggest product mappings Source: https://docs.revkeen.com/docs/api-reference/integrations_suggest_mappings **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Call the RevKeen AI service to propose product-mapping candidates for unmapped external packages. Inputs: the unmapped package list plus the merchant's product catalogue. Output: a ranked list of suggested `(external_id, revkeen_product_id, confidence)` tuples. No state is written — the merchant must confirm and `PUT` the mapping set. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Update sync interval Source: https://docs.revkeen.com/docs/api-reference/integrations_sync_interval_update **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update the cadence (in minutes) at which the sync cron picks up an integration. Minimum 5 minutes for most providers; check the provider's rate-limit documentation before shortening. Changes take effect on the next cron tick. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get sync log by ID Source: https://docs.revkeen.com/docs/api-reference/integrations_sync_log_by_id **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Return the full detail of a single sync log entry, including the raw request/response snapshot captured at the time of the attempt. Used for drill-down from the Sync History dashboard and for support-ticket debugging. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List sync logs Source: https://docs.revkeen.com/docs/api-reference/integrations_sync_logs_list **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Return sync log entries with optional filters (`status`, `resourceType`, `since`, `until`, pagination). Each log entry captures the outcome of a single resource-record sync attempt — success, failure reason, conflict resolution notes, and the retryable flag. Drives the Sync History dashboard. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Get resource-level sync states Source: https://docs.revkeen.com/docs/api-reference/integrations_sync_states_list **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Return the cursor and last-sync timestamp for every resource type the integration tracks (patients / customers, invoices, products, payments, etc.). Used by the sync dashboard to surface which resource classes are up to date and which are lagging. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Get sync stats by resource type Source: https://docs.revkeen.com/docs/api-reference/integrations_sync_stats_by_type_get **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. --- Return the same aggregate counters as `/sync-stats` but grouped by resource type (invoices, customers, products, etc.). Used to surface which resource class is failing most often. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. --- # Get sync stats Source: https://docs.revkeen.com/docs/api-reference/integrations_sync_stats_get **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. --- Return aggregate counters for an integration — total runs, success / failure / conflict counts by window, average duration, next scheduled run. Computed on-the-fly from the sync logs table; may be slow for long-running integrations with millions of log entries. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. --- # Toggle integration sync Source: https://docs.revkeen.com/docs/api-reference/integrations_sync_toggle_update **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Enable or disable automatic sync for an integration without destroying stored credentials or mappings. Disabled integrations are skipped by the sync cron until re-enabled. Useful for temporary pauses during merchant off-boarding or provider-side maintenance windows. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Test integration credentials Source: https://docs.revkeen.com/docs/api-reference/integrations_test **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Validate credentials against the provider's authentication endpoint without activating the integration. Used by the activation wizard to surface credential errors before the merchant commits to a sync schedule. Returns `{ valid: true }` on success or `{ valid: false, reason }` with the provider's error message on failure. No state is persisted. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Trigger manual sync Source: https://docs.revkeen.com/docs/api-reference/integrations_trigger_sync **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `400 invalid_request` — malformed payload or failed validation. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Enqueue an immediate sync job for an already-active integration. By default only records modified since the last cursor are processed; pass `fullResync=true` to ignore the cursor and re-process every record — safe but expensive, useful after a schema change or to recover from drift. Returns `400` if the integration is not active. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `400 invalid_request` — malformed payload or failed validation. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get unmapped transaction attempts Source: https://docs.revkeen.com/docs/api-reference/integrations_unmapped_attempts_list **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Return aggregated unmapped-line-item attempts — external packages that appeared on synced invoices but had no product mapping. Grouped by external package with attempt counts and last-seen timestamps. Drives the 'Missing mappings' prompt in the integration dashboard. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/status` — Update integration status - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Update integration status Source: https://docs.revkeen.com/docs/api-reference/integrations_update_status **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Internal endpoint used by the sync worker to update the integration's status and last-sync timestamp after a run. Not intended for dashboard or external callers — requires the internal worker scope and is annotated `x-internal: true`. --- **Related endpoints** - `POST /integrations/{provider}/activate` — Activate integration - `POST /integrations/{provider}/deactivate` — Deactivate integration - `GET /integrations/{provider}` — Get integration status - `POST /integrations/{provider}/test` — Test integration credentials - `POST /integrations/{provider}/sync` — Trigger manual sync - `GET /integrations` — List all integrations - `PUT /integrations/{provider}/sync-toggle` — Toggle integration sync - `PUT /integrations/{provider}/sync-interval` — Update sync interval **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Add invoice comment Source: https://docs.revkeen.com/docs/api-reference/invoices_comments_add **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Add a comment to an invoice. Set isInternal to true for merchant-only comments. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # List invoice comments Source: https://docs.revkeen.com/docs/api-reference/invoices_comments_list **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List comments for an invoice. Use includeInternal=true to include internal comments (merchant only). --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Create invoice Source: https://docs.revkeen.com/docs/api-reference/invoices_create **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a new invoice. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Check credit eligibility Source: https://docs.revkeen.com/docs/api-reference/invoices_credit_eligibility **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Check if an invoice is eligible for credit notes and get the maximum creditable amount. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Issue credit note Source: https://docs.revkeen.com/docs/api-reference/invoices_credit_note_issue **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Issue a credit note for a paid or partially paid invoice. Use this instead of void for invoices that have received payment. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # List credit notes Source: https://docs.revkeen.com/docs/api-reference/invoices_credit_notes_list **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List all credit notes issued for an invoice. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Delete invoice Source: https://docs.revkeen.com/docs/api-reference/invoices_delete **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Delete an invoice. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Batch upsert invoices by external ID Source: https://docs.revkeen.com/docs/api-reference/invoices_external_batch **Related endpoints** - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create or update multiple invoices by external system ID. Supports up to 100 invoices per request with stale update protection and immutable field guardrails. --- **Related endpoints** - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Upsert invoice by external ID Source: https://docs.revkeen.com/docs/api-reference/invoices_external_upsert_by_external_id **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. - `422 unprocessable_entity` — business-rule failure (for example, refunding more than the original charge). **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create or update an invoice identified by external source and ID. Used by integrations (PracticeHub, Wodify) to sync invoices. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. - `422 unprocessable_entity` — business-rule failure (for example, refunding more than the original charge). **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Finalize an invoice Source: https://docs.revkeen.com/docs/api-reference/invoices_finalize **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Finalizes a draft invoice, locking it for payment. Assigns invoice number and generates public token. After finalization, financial fields become immutable. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get invoice Source: https://docs.revkeen.com/docs/api-reference/invoices_get **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments --- Get a single invoice by ID. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments --- # List invoices Source: https://docs.revkeen.com/docs/api-reference/invoices_list **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List invoices with pagination and filtering. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Record a payment Source: https://docs.revkeen.com/docs/api-reference/invoices_pay **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Records a manual payment against an invoice. Use this for cash, check, bank transfer, or other offline payments. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Refund invoice Source: https://docs.revkeen.com/docs/api-reference/invoices_refund **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Common errors** - `400 invalid_request` — malformed payload or failed validation. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Issue a full or partial refund for a paid invoice. Emits invoice.refunded notification to customer. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Common errors** - `400 invalid_request` — malformed payload or failed validation. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Reject invoice Source: https://docs.revkeen.com/docs/api-reference/invoices_reject **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `GET /invoices/{id}/comments` — List invoice comments **Common errors** - `400 invalid_request` — malformed payload or failed validation. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Reject an invoice during approval workflow. Returns invoice to draft status with rejection details. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `GET /invoices/{id}/comments` — List invoice comments **Common errors** - `400 invalid_request` — malformed payload or failed validation. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Send an invoice Source: https://docs.revkeen.com/docs/api-reference/invoices_send **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Sends an invoice to the customer via the specified channel (email, SMS, or WhatsApp). Invoice must be approved first. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Update invoice Source: https://docs.revkeen.com/docs/api-reference/invoices_update **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update an existing invoice. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice - `GET /invoices/{id}/comments` — List invoice comments **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Void an invoice Source: https://docs.revkeen.com/docs/api-reference/invoices_void **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Voids an invoice. Only invoices without recorded payments can be voided. Use refund instead for paid invoices. --- **Related endpoints** - `PUT /invoices/external/batch` — Batch upsert invoices by external ID - `GET /invoices` — List invoices - `POST /invoices` — Create invoice - `GET /invoices/{id}` — Get invoice - `PATCH /invoices/{id}` — Update invoice - `DELETE /invoices/{id}` — Delete invoice - `POST /invoices/{id}/refund` — Refund invoice - `POST /invoices/{id}/reject` — Reject invoice **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a meter Source: https://docs.revkeen.com/docs/api-reference/meters_create **Related endpoints** - `GET /meters` — List meters - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a new usage meter. Meters define how usage events are aggregated for billing. --- **Related endpoints** - `GET /meters` — List meters - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a meter price Source: https://docs.revkeen.com/docs/api-reference/meters_create_price **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a usage price for a meter with a specific pricing model (per_unit, graduated, volume, or package). --- **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Deactivate a meter price Source: https://docs.revkeen.com/docs/api-reference/meters_deactivate_price **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Deactivate a usage price. Deactivated prices cannot be used for new subscriptions but existing subscriptions continue until the end of their billing period. --- **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get a meter Source: https://docs.revkeen.com/docs/api-reference/meters_get **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve a single meter by ID. --- **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List meters Source: https://docs.revkeen.com/docs/api-reference/meters_list **Related endpoints** - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List all usage meters with optional filtering and pagination. --- **Related endpoints** - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # List meter prices Source: https://docs.revkeen.com/docs/api-reference/meters_list_prices **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- List all prices attached to a meter, including their tier configurations. --- **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # Update a meter Source: https://docs.revkeen.com/docs/api-reference/meters_update **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update a meter's configuration. Note: `event_name` and `aggregation` are immutable after creation. --- **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `PATCH /meters/{meterId}/prices/{priceId}` — Update a meter price - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Update a meter price Source: https://docs.revkeen.com/docs/api-reference/meters_update_price **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update an existing usage price configuration. The pricing_model is immutable. --- **Related endpoints** - `GET /meters` — List meters - `POST /meters` — Create a meter - `GET /meters/{id}` — Get a meter - `PATCH /meters/{id}` — Update a meter - `POST /meters/{meterId}/prices` — Create a meter price - `GET /meters/{meterId}/prices` — List meter prices - `POST /meters/{meterId}/prices/{priceId}/deactivate` — Deactivate a meter price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Cancel an order Source: https://docs.revkeen.com/docs/api-reference/orders_cancel **Related endpoints** - `GET /orders` — List orders - `POST /orders` — Create an order - `GET /orders/{id}` — Retrieve an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Cancels an order. Only orders that haven't been paid or fulfilled can be canceled. --- **Related endpoints** - `GET /orders` — List orders - `POST /orders` — Create an order - `GET /orders/{id}` — Retrieve an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create an order Source: https://docs.revkeen.com/docs/api-reference/orders_create **Related endpoints** - `GET /orders` — List orders - `GET /orders/{id}` — Retrieve an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/cancel` — Cancel an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Creates a new order with line items. Orders start in draft status. --- **Related endpoints** - `GET /orders` — List orders - `GET /orders/{id}` — Retrieve an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/cancel` — Cancel an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Fulfill an order Source: https://docs.revkeen.com/docs/api-reference/orders_fulfill **Related endpoints** - `GET /orders` — List orders - `POST /orders` — Create an order - `GET /orders/{id}` — Retrieve an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/cancel` — Cancel an order **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Mark an order as fulfilled. Optionally include shipping tracking information. --- **Related endpoints** - `GET /orders` — List orders - `POST /orders` — Create an order - `GET /orders/{id}` — Retrieve an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/cancel` — Cancel an order **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve an order Source: https://docs.revkeen.com/docs/api-reference/orders_get **Related endpoints** - `GET /orders` — List orders - `POST /orders` — Create an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/cancel` — Cancel an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieves an order by its ID, including line items. --- **Related endpoints** - `GET /orders` — List orders - `POST /orders` — Create an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/cancel` — Cancel an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List orders Source: https://docs.revkeen.com/docs/api-reference/orders_list **Related endpoints** - `POST /orders` — Create an order - `GET /orders/{id}` — Retrieve an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/cancel` — Cancel an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List all orders for the authenticated merchant. Supports filtering and cursor-based pagination. --- **Related endpoints** - `POST /orders` — Create an order - `GET /orders/{id}` — Retrieve an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/cancel` — Cancel an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Pay for an order Source: https://docs.revkeen.com/docs/api-reference/orders_pay **Related endpoints** - `GET /orders` — List orders - `POST /orders` — Create an order - `GET /orders/{id}` — Retrieve an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/cancel` — Cancel an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Process payment for an order. Creates an invoice and charges the customer's payment method. --- **Related endpoints** - `GET /orders` — List orders - `POST /orders` — Create an order - `GET /orders/{id}` — Retrieve an order - `PATCH /orders/{id}` — Update an order - `POST /orders/{id}/cancel` — Cancel an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Update an order Source: https://docs.revkeen.com/docs/api-reference/orders_update **Related endpoints** - `GET /orders` — List orders - `POST /orders` — Create an order - `GET /orders/{id}` — Retrieve an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/cancel` — Cancel an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Updates order metadata, notes, or customer association before fulfillment. --- **Related endpoints** - `GET /orders` — List orders - `POST /orders` — Create an order - `GET /orders/{id}` — Retrieve an order - `POST /orders/{id}/pay` — Pay for an order - `POST /orders/{id}/cancel` — Cancel an order - `POST /orders/{id}/fulfill` — Fulfill an order **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Cancel a payment intent Source: https://docs.revkeen.com/docs/api-reference/payment_intents_cancel **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents` — List payment intents - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Cancels a payment intent. Cannot cancel if already succeeded or canceled. --- **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents` — List payment intents - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Capture a payment intent Source: https://docs.revkeen.com/docs/api-reference/payment_intents_capture **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents` — List payment intents - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Captures a payment intent that was created with capture_method=manual. --- **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents` — List payment intents - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Confirm a payment intent Source: https://docs.revkeen.com/docs/api-reference/payment_intents_confirm **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents` — List payment intents - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Confirms the payment intent. May return requires_action if 3DS authentication is needed. --- **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents` — List payment intents - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a payment intent Source: https://docs.revkeen.com/docs/api-reference/payment_intents_create **Related endpoints** - `GET /payment-intents` — List payment intents - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Creates a payment intent to orchestrate payment collection with support for 3DS/SCA authentication. --- **Related endpoints** - `GET /payment-intents` — List payment intents - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve a payment intent Source: https://docs.revkeen.com/docs/api-reference/payment_intents_get **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents` — List payment intents - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieves a payment intent by its ID (pi_xxx). --- **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents` — List payment intents - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List payment intents Source: https://docs.revkeen.com/docs/api-reference/payment_intents_list **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Returns a list of payment intents with optional filtering. --- **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}` — Update a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Update a payment intent Source: https://docs.revkeen.com/docs/api-reference/payment_intents_update **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents` — List payment intents - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Updates a payment intent. Only certain fields can be updated based on the intent's status. --- **Related endpoints** - `POST /payment-intents` — Create a payment intent - `GET /payment-intents` — List payment intents - `GET /payment-intents/{id}` — Retrieve a payment intent - `POST /payment-intents/{id}/confirm` — Confirm a payment intent - `POST /payment-intents/{id}/capture` — Capture a payment intent - `POST /payment-intents/{id}/cancel` — Cancel a payment intent **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Activate a payment link (deprecated) Source: https://docs.revkeen.com/docs/api-reference/payment_links_activate **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- **Deprecated — use `PATCH /v2/payment-links/{id}/status` with `status: "active"` instead.** This convenience endpoint will be removed in a future API version. Enable a payment link to accept payments. Cannot be used on archived links. --- **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Archive a payment link (deprecated) Source: https://docs.revkeen.com/docs/api-reference/payment_links_archive **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- **Deprecated — use `PATCH /v2/payment-links/{id}/status` with `status: "archived"` instead.** This convenience endpoint will be removed in a future API version. Permanently disable a payment link. This action cannot be undone. --- **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a new payment link Source: https://docs.revkeen.com/docs/api-reference/payment_links_create **Related endpoints** - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a new payment link for invoices, subscriptions, or custom amounts --- **Related endpoints** - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Deactivate a payment link (deprecated) Source: https://docs.revkeen.com/docs/api-reference/payment_links_deactivate **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- **Deprecated — use `PATCH /v2/payment-links/{id}/status` with `status: "inactive"` instead.** This convenience endpoint will be removed in a future API version. Temporarily disable a payment link. It can be reactivated later. --- **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Expire a payment link (deprecated) Source: https://docs.revkeen.com/docs/api-reference/payment_links_expire **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- **Deprecated — use `PATCH /v2/payment-links/{id}/status` with `status: "expired"` instead.** This convenience endpoint will be removed in a future API version. Mark a payment link as expired, preventing further use. --- **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get payment link by ID Source: https://docs.revkeen.com/docs/api-reference/payment_links_get **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve a payment link by its UUID or public_id --- **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List payment links Source: https://docs.revkeen.com/docs/api-reference/payment_links_list **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List payment links for the authenticated merchant with pagination and filters --- **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `PATCH /payment-links/{id}/status` — Update payment link status - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Update payment link status Source: https://docs.revkeen.com/docs/api-reference/payment_links_update **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Change the status of a payment link. Active links accept payments, inactive links are temporarily disabled, and archived links are permanently disabled and cannot be reactivated. --- **Related endpoints** - `POST /payment-links` — Create a new payment link - `GET /payment-links` — List payment links - `GET /payment-links/{id}` — Get payment link by ID - `POST /payment-links/{id}/expire` — Expire a payment link (deprecated) - `POST /payment-links/{id}/deactivate` — Deactivate a payment link (deprecated) - `POST /payment-links/{id}/activate` — Activate a payment link (deprecated) - `POST /payment-links/{id}/archive` — Archive a payment link (deprecated) **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve a payment Source: https://docs.revkeen.com/docs/api-reference/payments_get **Related endpoints** - `GET /payments` — List payments **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieves a payment by its ID. --- **Related endpoints** - `GET /payments` — List payments **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List payments Source: https://docs.revkeen.com/docs/api-reference/payments_list **Related endpoints** - `GET /payments/{id}` — Retrieve a payment **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List all payments for the authenticated merchant. Supports filtering and cursor-based pagination. --- **Related endpoints** - `GET /payments/{id}` — Retrieve a payment **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Get payout by ID Source: https://docs.revkeen.com/docs/api-reference/payouts_get **Related endpoints** - `GET /payouts` — List payouts - `GET /payouts/{id}/payments` — Get payments in a payout **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve a single payout by its public ID (pyt_xxx) or internal UUID. --- **Related endpoints** - `GET /payouts` — List payouts - `GET /payouts/{id}/payments` — Get payments in a payout **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List payouts Source: https://docs.revkeen.com/docs/api-reference/payouts_list **Related endpoints** - `GET /payouts/{id}` — Get payout by ID - `GET /payouts/{id}/payments` — Get payments in a payout **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve a paginated list of payouts/settlements with optional filters. Results are ordered by creation date (newest first). --- **Related endpoints** - `GET /payouts/{id}` — Get payout by ID - `GET /payouts/{id}/payments` — Get payments in a payout **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Get payments in a payout Source: https://docs.revkeen.com/docs/api-reference/payouts_payments_list **Related endpoints** - `GET /payouts` — List payouts - `GET /payouts/{id}` — Get payout by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve all payments that were included in a specific payout batch. --- **Related endpoints** - `GET /payouts` — List payouts - `GET /payouts/{id}` — Get payout by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Archive a price Source: https://docs.revkeen.com/docs/api-reference/prices_archive **Related endpoints** - `GET /prices` — List prices - `POST /prices` — Create a price - `GET /prices/{id}` — Retrieve a price - `PATCH /prices/{id}` — Update a price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Archives a price by setting active to false. The price remains in the system but cannot be used for new purchases. --- **Related endpoints** - `GET /prices` — List prices - `POST /prices` — Create a price - `GET /prices/{id}` — Retrieve a price - `PATCH /prices/{id}` — Update a price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a price Source: https://docs.revkeen.com/docs/api-reference/prices_create **Related endpoints** - `GET /prices` — List prices - `GET /prices/{id}` — Retrieve a price - `PATCH /prices/{id}` — Update a price - `DELETE /prices/{id}` — Archive a price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Creates a new price for a product. Supports fixed, pay-what-you-want, and free pricing models. --- **Related endpoints** - `GET /prices` — List prices - `GET /prices/{id}` — Retrieve a price - `PATCH /prices/{id}` — Update a price - `DELETE /prices/{id}` — Archive a price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve a price Source: https://docs.revkeen.com/docs/api-reference/prices_get **Related endpoints** - `GET /prices` — List prices - `POST /prices` — Create a price - `PATCH /prices/{id}` — Update a price - `DELETE /prices/{id}` — Archive a price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieves a price by its ID. --- **Related endpoints** - `GET /prices` — List prices - `POST /prices` — Create a price - `PATCH /prices/{id}` — Update a price - `DELETE /prices/{id}` — Archive a price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List prices Source: https://docs.revkeen.com/docs/api-reference/prices_list **Related endpoints** - `POST /prices` — Create a price - `GET /prices/{id}` — Retrieve a price - `PATCH /prices/{id}` — Update a price - `DELETE /prices/{id}` — Archive a price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List all prices for the authenticated merchant. Supports filtering and cursor-based pagination. --- **Related endpoints** - `POST /prices` — Create a price - `GET /prices/{id}` — Retrieve a price - `PATCH /prices/{id}` — Update a price - `DELETE /prices/{id}` — Archive a price **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Update a price Source: https://docs.revkeen.com/docs/api-reference/prices_update **Related endpoints** - `GET /prices` — List prices - `POST /prices` — Create a price - `GET /prices/{id}` — Retrieve a price - `DELETE /prices/{id}` — Archive a price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Updates a price. Only certain fields can be updated (active, nickname, lookup_key, metadata). Core pricing fields are immutable. --- **Related endpoints** - `GET /prices` — List prices - `POST /prices` — Create a price - `GET /prices/{id}` — Retrieve a price - `DELETE /prices/{id}` — Archive a price **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create product Source: https://docs.revkeen.com/docs/api-reference/products_create **Related endpoints** - `GET /products` — List products - `GET /products/{id}` — Get product by ID - `PATCH /products/{id}` — Update product - `PUT /products/external/{source}/{externalId}` — Upsert product by external ID - `PUT /products/external/batch` — Batch upsert products by external ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a new product. Requires 'products:write' scope. --- **Related endpoints** - `GET /products` — List products - `GET /products/{id}` — Get product by ID - `PATCH /products/{id}` — Update product - `PUT /products/external/{source}/{externalId}` — Upsert product by external ID - `PUT /products/external/batch` — Batch upsert products by external ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Batch upsert products by external ID Source: https://docs.revkeen.com/docs/api-reference/products_external_batch **Related endpoints** - `GET /products` — List products - `POST /products` — Create product - `GET /products/{id}` — Get product by ID - `PATCH /products/{id}` — Update product - `PUT /products/external/{source}/{externalId}` — Upsert product by external ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create or update multiple products by external system ID. Supports up to 100 products per request with stale update protection. --- **Related endpoints** - `GET /products` — List products - `POST /products` — Create product - `GET /products/{id}` — Get product by ID - `PATCH /products/{id}` — Update product - `PUT /products/external/{source}/{externalId}` — Upsert product by external ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Upsert product by external ID Source: https://docs.revkeen.com/docs/api-reference/products_external_upsert **Related endpoints** - `GET /products` — List products - `POST /products` — Create product - `GET /products/{id}` — Get product by ID - `PATCH /products/{id}` — Update product - `PUT /products/external/batch` — Batch upsert products by external ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create or update a product by external system ID. Uses stale update protection. --- **Related endpoints** - `GET /products` — List products - `POST /products` — Create product - `GET /products/{id}` — Get product by ID - `PATCH /products/{id}` — Update product - `PUT /products/external/batch` — Batch upsert products by external ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get product by ID Source: https://docs.revkeen.com/docs/api-reference/products_get **Related endpoints** - `GET /products` — List products - `POST /products` — Create product - `PATCH /products/{id}` — Update product - `PUT /products/external/{source}/{externalId}` — Upsert product by external ID - `PUT /products/external/batch` — Batch upsert products by external ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Get a product by its ID. Requires 'products:read' scope. --- **Related endpoints** - `GET /products` — List products - `POST /products` — Create product - `PATCH /products/{id}` — Update product - `PUT /products/external/{source}/{externalId}` — Upsert product by external ID - `PUT /products/external/batch` — Batch upsert products by external ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List products Source: https://docs.revkeen.com/docs/api-reference/products_list **Related endpoints** - `POST /products` — Create product - `GET /products/{id}` — Get product by ID - `PATCH /products/{id}` — Update product - `PUT /products/external/{source}/{externalId}` — Upsert product by external ID - `PUT /products/external/batch` — Batch upsert products by external ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List products with pagination and optional search. --- **Related endpoints** - `POST /products` — Create product - `GET /products/{id}` — Get product by ID - `PATCH /products/{id}` — Update product - `PUT /products/external/{source}/{externalId}` — Upsert product by external ID - `PUT /products/external/batch` — Batch upsert products by external ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Update product Source: https://docs.revkeen.com/docs/api-reference/products_update **Related endpoints** - `GET /products` — List products - `POST /products` — Create product - `GET /products/{id}` — Get product by ID - `PUT /products/external/{source}/{externalId}` — Upsert product by external ID - `PUT /products/external/batch` — Batch upsert products by external ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update an existing product. Requires 'products:write' scope. --- **Related endpoints** - `GET /products` — List products - `POST /products` — Create product - `GET /products/{id}` — Get product by ID - `PUT /products/external/{source}/{externalId}` — Upsert product by external ID - `PUT /products/external/batch` — Batch upsert products by external ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a refund Source: https://docs.revkeen.com/docs/api-reference/refunds_create **Related endpoints** - `GET /refunds` — List refunds - `GET /refunds/{id}` — Get refund by ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Initiate a refund for a payment. The refund will be processed through the original payment gateway. --- **Related endpoints** - `GET /refunds` — List refunds - `GET /refunds/{id}` — Get refund by ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get refund by ID Source: https://docs.revkeen.com/docs/api-reference/refunds_get **Related endpoints** - `GET /refunds` — List refunds - `POST /refunds` — Create a refund **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve a single refund by its public ID (ref_xxx) or internal UUID. --- **Related endpoints** - `GET /refunds` — List refunds - `POST /refunds` — Create a refund **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List refunds Source: https://docs.revkeen.com/docs/api-reference/refunds_list **Related endpoints** - `POST /refunds` — Create a refund - `GET /refunds/{id}` — Get refund by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve a paginated list of refunds with optional filters. Results are ordered by creation date (newest first). --- **Related endpoints** - `POST /refunds` — Create a refund - `GET /refunds/{id}` — Get refund by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Add item to subscription Source: https://docs.revkeen.com/docs/api-reference/subscription_items_create **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Add a new line item to an existing subscription. This is used for multi-product subscriptions where items share the same billing interval. --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Remove item from subscription Source: https://docs.revkeen.com/docs/api-reference/subscription_items_delete **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Remove a line item from a subscription. Cannot remove the last item - cancel the subscription instead. --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # List subscription items Source: https://docs.revkeen.com/docs/api-reference/subscription_items_list **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve all line items for a specific subscription. Items represent individual products/prices within a multi-product subscription. --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Update subscription item Source: https://docs.revkeen.com/docs/api-reference/subscription_items_update **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update a subscription item's quantity, description, price, or fulfillment type. --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Cancel a subscription schedule Source: https://docs.revkeen.com/docs/api-reference/subscription_schedules_cancel **Related endpoints** - `POST /subscription-schedules` — Create a subscription schedule - `GET /subscription-schedules` — List subscription schedules - `GET /subscription-schedules/{id}` — Retrieve a subscription schedule - `POST /subscription-schedules/{id}` — Update a subscription schedule - `POST /subscription-schedules/{id}/release` — Release a subscription schedule **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Cancels a subscription schedule. Only schedules in 'not_started' or 'active' status can be canceled. --- **Related endpoints** - `POST /subscription-schedules` — Create a subscription schedule - `GET /subscription-schedules` — List subscription schedules - `GET /subscription-schedules/{id}` — Retrieve a subscription schedule - `POST /subscription-schedules/{id}` — Update a subscription schedule - `POST /subscription-schedules/{id}/release` — Release a subscription schedule **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a subscription schedule Source: https://docs.revkeen.com/docs/api-reference/subscription_schedules_create **Related endpoints** - `GET /subscription-schedules` — List subscription schedules - `GET /subscription-schedules/{id}` — Retrieve a subscription schedule - `POST /subscription-schedules/{id}` — Update a subscription schedule - `POST /subscription-schedules/{id}/cancel` — Cancel a subscription schedule - `POST /subscription-schedules/{id}/release` — Release a subscription schedule **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Creates a subscription schedule to manage future subscription changes. Schedules define phases with different pricing/plans that transition automatically. --- **Related endpoints** - `GET /subscription-schedules` — List subscription schedules - `GET /subscription-schedules/{id}` — Retrieve a subscription schedule - `POST /subscription-schedules/{id}` — Update a subscription schedule - `POST /subscription-schedules/{id}/cancel` — Cancel a subscription schedule - `POST /subscription-schedules/{id}/release` — Release a subscription schedule **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve a subscription schedule Source: https://docs.revkeen.com/docs/api-reference/subscription_schedules_get **Related endpoints** - `POST /subscription-schedules` — Create a subscription schedule - `GET /subscription-schedules` — List subscription schedules - `POST /subscription-schedules/{id}` — Update a subscription schedule - `POST /subscription-schedules/{id}/cancel` — Cancel a subscription schedule - `POST /subscription-schedules/{id}/release` — Release a subscription schedule **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieves a subscription schedule by its ID. --- **Related endpoints** - `POST /subscription-schedules` — Create a subscription schedule - `GET /subscription-schedules` — List subscription schedules - `POST /subscription-schedules/{id}` — Update a subscription schedule - `POST /subscription-schedules/{id}/cancel` — Cancel a subscription schedule - `POST /subscription-schedules/{id}/release` — Release a subscription schedule **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List subscription schedules Source: https://docs.revkeen.com/docs/api-reference/subscription_schedules_list **Related endpoints** - `POST /subscription-schedules` — Create a subscription schedule - `GET /subscription-schedules/{id}` — Retrieve a subscription schedule - `POST /subscription-schedules/{id}` — Update a subscription schedule - `POST /subscription-schedules/{id}/cancel` — Cancel a subscription schedule - `POST /subscription-schedules/{id}/release` — Release a subscription schedule **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Returns a list of subscription schedules with optional filters. --- **Related endpoints** - `POST /subscription-schedules` — Create a subscription schedule - `GET /subscription-schedules/{id}` — Retrieve a subscription schedule - `POST /subscription-schedules/{id}` — Update a subscription schedule - `POST /subscription-schedules/{id}/cancel` — Cancel a subscription schedule - `POST /subscription-schedules/{id}/release` — Release a subscription schedule **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Release a subscription schedule Source: https://docs.revkeen.com/docs/api-reference/subscription_schedules_release **Related endpoints** - `POST /subscription-schedules` — Create a subscription schedule - `GET /subscription-schedules` — List subscription schedules - `GET /subscription-schedules/{id}` — Retrieve a subscription schedule - `POST /subscription-schedules/{id}` — Update a subscription schedule - `POST /subscription-schedules/{id}/cancel` — Cancel a subscription schedule **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Releases a subscription schedule, detaching it from the subscription. The subscription becomes standalone and continues normally. --- **Related endpoints** - `POST /subscription-schedules` — Create a subscription schedule - `GET /subscription-schedules` — List subscription schedules - `GET /subscription-schedules/{id}` — Retrieve a subscription schedule - `POST /subscription-schedules/{id}` — Update a subscription schedule - `POST /subscription-schedules/{id}/cancel` — Cancel a subscription schedule **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Update a subscription schedule Source: https://docs.revkeen.com/docs/api-reference/subscription_schedules_update **Related endpoints** - `POST /subscription-schedules` — Create a subscription schedule - `GET /subscription-schedules` — List subscription schedules - `GET /subscription-schedules/{id}` — Retrieve a subscription schedule - `POST /subscription-schedules/{id}/cancel` — Cancel a subscription schedule - `POST /subscription-schedules/{id}/release` — Release a subscription schedule **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Updates a subscription schedule. Only schedules in 'not_started' or 'active' status can be updated. --- **Related endpoints** - `POST /subscription-schedules` — Create a subscription schedule - `GET /subscription-schedules` — List subscription schedules - `GET /subscription-schedules/{id}` — Retrieve a subscription schedule - `POST /subscription-schedules/{id}/cancel` — Cancel a subscription schedule - `POST /subscription-schedules/{id}/release` — Release a subscription schedule **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Cancel subscription Source: https://docs.revkeen.com/docs/api-reference/subscriptions_cancel **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Cancel a subscription either immediately or at the end of the current billing period. **Modes:** - `immediately`: Status set to "canceled", access revoked now - `period_end`: cancelAtPeriodEnd flag set, access continues until period end --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Change subscription plan Source: https://docs.revkeen.com/docs/api-reference/subscriptions_change_plan **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Change the plan for an existing subscription with optional proration --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Change subscription quantity Source: https://docs.revkeen.com/docs/api-reference/subscriptions_change_quantity **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update the quantity for a subscription with optional proration --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create a new subscription Source: https://docs.revkeen.com/docs/api-reference/subscriptions_create **Related endpoints** - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a new subscription for a customer --- **Related endpoints** - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Delete subscription Source: https://docs.revkeen.com/docs/api-reference/subscriptions_delete **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Cancel an active subscription immediately or at period end --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get subscription by ID Source: https://docs.revkeen.com/docs/api-reference/subscriptions_get **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve detailed information about a specific subscription --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List subscriptions Source: https://docs.revkeen.com/docs/api-reference/subscriptions_list **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve a paginated list of subscriptions with optional filters --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Pause subscription Source: https://docs.revkeen.com/docs/api-reference/subscriptions_pause **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Pause an active subscription. While paused: - No new invoices are generated - The subscription status changes to "paused" - The customer retains access until the current period ends (depending on your business logic) **Behavior Options:** - `keep_as_draft`: Invoices are created as drafts (default) - `mark_uncollectible`: Invoices are marked uncollectible - `void`: Invoices are voided Optionally set `resumes_at` to automatically resume at a future date. --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Preview subscription renewal Source: https://docs.revkeen.com/docs/api-reference/subscriptions_preview_renewal **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Preview the upcoming renewal dates and amounts for an existing subscription. This uses the same billing calculation logic as the actual scheduler to show exactly when and how much the subscription will be billed (Key Invariant #4: Preview === Scheduler). --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Reactivate subscription Source: https://docs.revkeen.com/docs/api-reference/subscriptions_reactivate **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Reverse a scheduled cancellation. The subscription must be active with cancelAtPeriodEnd=true. Clears the cancellation flag and the subscription continues as normal. --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Resume subscription Source: https://docs.revkeen.com/docs/api-reference/subscriptions_resume **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Resume a paused subscription. The subscription status changes back to "active" and normal billing resumes. If the subscription was paused with draft invoices, you may need to manually finalize and send them. --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `PATCH /subscriptions/{id}` — Update subscription details - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Update subscription details Source: https://docs.revkeen.com/docs/api-reference/subscriptions_update **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update an existing subscription's properties --- **Related endpoints** - `POST /subscriptions` — Create a new subscription - `GET /subscriptions` — List subscriptions - `GET /subscriptions/{id}` — Get subscription by ID - `DELETE /subscriptions/{id}` — Delete subscription - `POST /subscriptions/{id}/change-plan` — Change subscription plan - `POST /subscriptions/{id}/change-quantity` — Change subscription quantity - `POST /subscriptions/{id}/preview-renewal` — Preview subscription renewal - `POST /subscriptions/{id}/pause` — Pause subscription **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get sync states for integration Source: https://docs.revkeen.com/docs/api-reference/sync_state_list **Related endpoints** - `PUT /sync-state/{source}/{merchantId}/{resourceType}` — Update sync state **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Get all sync states for a specific integration (by provider and merchant). --- **Related endpoints** - `PUT /sync-state/{source}/{merchantId}/{resourceType}` — Update sync state **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Update sync state Source: https://docs.revkeen.com/docs/api-reference/sync_state_update **Related endpoints** - `GET /sync-state/{source}/{merchantId}` — Get sync states for integration **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update or create sync state for a specific resource type. Used by worker after sync jobs. --- **Related endpoints** - `GET /sync-state/{source}/{merchantId}` — Get sync states for integration **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve a terminal device Source: https://docs.revkeen.com/docs/api-reference/terminal_devices_get **Related endpoints** - `GET /terminal-devices` — List terminal devices **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Get a terminal device by ID, including its current status and heartbeat information. --- **Related endpoints** - `GET /terminal-devices` — List terminal devices **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List terminal devices Source: https://docs.revkeen.com/docs/api-reference/terminal_devices_list **Related endpoints** - `GET /terminal-devices/{id}` — Retrieve a terminal device **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List all terminal devices registered for the authenticated merchant. Use this endpoint to discover device IDs before initiating a terminal payment. --- **Related endpoints** - `GET /terminal-devices/{id}` — Retrieve a terminal device **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Cancel a terminal payment Source: https://docs.revkeen.com/docs/api-reference/terminal_payments_cancel **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments` — List terminal payments - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Cancel an in-progress terminal payment. Only payments with status `requested` or `in_progress` can be cancelled. --- **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments` — List terminal payments - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Initiate a terminal payment Source: https://docs.revkeen.com/docs/api-reference/terminal_payments_create **Related endpoints** - `GET /terminal-payments` — List terminal payments - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. - `422 unprocessable_entity` — business-rule failure (for example, refunding more than the original charge). **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Send a card-present payment request to a specific terminal device. The payment is dispatched to the merchant's POS connector which forwards it to the PAX terminal. **Device Selection:** You must provide a `device_id`. Use [List Terminal Devices](#tag/Terminal-Devices/operation/terminal_devices_list) to discover available devices and their IDs. Even merchants with a single terminal must pass the `device_id` explicitly — there is no auto-routing fallback. **Invoice Association:** `invoice_id` is optional. Omit it for walk-in or ad-hoc payments where no pre-existing invoice exists. The response returns immediately with status `requested`. Subscribe to terminal webhooks (`billing.terminal_payment.succeeded`, `billing.terminal_payment.declined`, etc.) to receive the outcome asynchronously. --- **Related endpoints** - `GET /terminal-payments` — List terminal payments - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. - `403 permission_denied` — key lacks the required scope, or the resource belongs to a different merchant. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. - `422 unprocessable_entity` — business-rule failure (for example, refunding more than the original charge). **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Retrieve a terminal payment Source: https://docs.revkeen.com/docs/api-reference/terminal_payments_get **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments` — List terminal payments - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Get a terminal payment attempt by ID. --- **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments` — List terminal payments - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List terminal payments Source: https://docs.revkeen.com/docs/api-reference/terminal_payments_list **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List terminal payment attempts for the authenticated merchant. Supports filtering by invoice, status, type, and device. Uses cursor-based pagination. --- **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Refund a terminal payment Source: https://docs.revkeen.com/docs/api-reference/terminal_payments_refund **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments` — List terminal payments - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `422 unprocessable_entity` — business-rule failure (for example, refunding more than the original charge). **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Initiate a refund for a completed terminal payment. The refund is sent to the same terminal that processed the original sale. `amount_minor` is optional — omit for a full refund. For partial refunds, specify the amount in minor units. The refund command is dispatched asynchronously. Subscribe to `billing.terminal_refund.succeeded` webhooks for the outcome. --- **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments` — List terminal payments - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/void` — Void a terminal payment **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `422 unprocessable_entity` — business-rule failure (for example, refunding more than the original charge). **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Void a terminal payment Source: https://docs.revkeen.com/docs/api-reference/terminal_payments_void **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments` — List terminal payments - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `422 unprocessable_entity` — business-rule failure (for example, refunding more than the original charge). **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Void a completed terminal payment. Voids are always for the full amount — partial voids are not supported. The void is sent to the same terminal that processed the original sale. Voids are only possible for unsettled transactions. If the transaction has already settled, use a refund instead. The void command is dispatched asynchronously. Subscribe to `billing.terminal_void.succeeded` webhooks for the outcome. --- **Related endpoints** - `POST /terminal-payments` — Initiate a terminal payment - `GET /terminal-payments` — List terminal payments - `GET /terminal-payments/{id}` — Retrieve a terminal payment - `POST /terminal-payments/{id}/cancel` — Cancel a terminal payment - `POST /terminal-payments/{id}/refund` — Refund a terminal payment **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `422 unprocessable_entity` — business-rule failure (for example, refunding more than the original charge). **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get transaction by ID Source: https://docs.revkeen.com/docs/api-reference/transactions_get **Related endpoints** - `GET /transactions` — List transactions **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve a single transaction by its ID. --- **Related endpoints** - `GET /transactions` — List transactions **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List transactions Source: https://docs.revkeen.com/docs/api-reference/transactions_list **Related endpoints** - `GET /transactions/{id}` — Get transaction by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List all transactions for the authenticated merchant. Transactions represent the unified financial truth — every sale, refund, void, capture, dispute, and adjustment. --- **Related endpoints** - `GET /transactions/{id}` — Get transaction by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Get current usage balance Source: https://docs.revkeen.com/docs/api-reference/usage_balance_get **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. --- Returns the current usage balance for a customer or subscription in the active billing period. Shows per-meter breakdown with included allowance, overage, estimated charges, and margin data. --- **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. --- # Get aggregated usage Source: https://docs.revkeen.com/docs/api-reference/usage_events_aggregate **Related endpoints** - `POST /usage-events` — Ingest usage events - `GET /usage-events` — Query usage events - `POST /usage-events/dry-run` — Dry-run usage events **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. --- Get aggregated usage for a specific meter over a time range. Returns the computed value using the meter's aggregation method. --- **Related endpoints** - `POST /usage-events` — Ingest usage events - `GET /usage-events` — Query usage events - `POST /usage-events/dry-run` — Dry-run usage events **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. --- # Dry-run usage events Source: https://docs.revkeen.com/docs/api-reference/usage_events_dry_run **Related endpoints** - `POST /usage-events` — Ingest usage events - `GET /usage-events` — Query usage events - `GET /usage-events/aggregate/{meterId}` — Get aggregated usage **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Validate usage events without persisting them. Returns acceptance/rejection reasons that mirror real ingestion rules. --- **Related endpoints** - `POST /usage-events` — Ingest usage events - `GET /usage-events` — Query usage events - `GET /usage-events/aggregate/{meterId}` — Get aggregated usage **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Ingest usage events Source: https://docs.revkeen.com/docs/api-reference/usage_events_ingest **Related endpoints** - `GET /usage-events` — Query usage events - `POST /usage-events/dry-run` — Dry-run usage events - `GET /usage-events/aggregate/{meterId}` — Get aggregated usage **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Send usage events for billing. Accepts a single event or a batch of up to 1000 events. **Single event:** Send the event object directly in the request body. **Batch:** Wrap events in an `events` array. Events are matched to meters by `name` (event name) or `meter_id`. At least one of `customer_id`, `external_customer_id`, or `subscription_id` is required. --- **Related endpoints** - `GET /usage-events` — Query usage events - `POST /usage-events/dry-run` — Dry-run usage events - `GET /usage-events/aggregate/{meterId}` — Get aggregated usage **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Query usage events Source: https://docs.revkeen.com/docs/api-reference/usage_events_list **Related endpoints** - `POST /usage-events` — Ingest usage events - `POST /usage-events/dry-run` — Dry-run usage events - `GET /usage-events/aggregate/{meterId}` — Get aggregated usage **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List usage events with optional filters. Returns up to 100 events per request. --- **Related endpoints** - `POST /usage-events` — Ingest usage events - `POST /usage-events/dry-run` — Dry-run usage events - `GET /usage-events/aggregate/{meterId}` — Get aggregated usage **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Create a void Source: https://docs.revkeen.com/docs/api-reference/voids_create **Related endpoints** - `GET /voids` — List voids - `GET /voids/{id}` — Get void by ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Void a payment that has not yet settled. Voids are always for the full amount. If the payment has already settled, use a refund instead. --- **Related endpoints** - `GET /voids` — List voids - `GET /voids/{id}` — Get void by ID **Common errors** - `400 invalid_request` — malformed payload or failed validation. - `401 unauthenticated` — missing, malformed, or revoked API key. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get void by ID Source: https://docs.revkeen.com/docs/api-reference/voids_get **Related endpoints** - `GET /voids` — List voids - `POST /voids` — Create a void **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve a single void by its public ID (void_xxx) or internal UUID. --- **Related endpoints** - `GET /voids` — List voids - `POST /voids` — Create a void **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List voids Source: https://docs.revkeen.com/docs/api-reference/voids_list **Related endpoints** - `POST /voids` — Create a void - `GET /voids/{id}` — Get void by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- Retrieve a paginated list of voids with optional filters. Results are ordered by creation date (newest first). Voids are full-amount cancellations of unsettled transactions. --- **Related endpoints** - `POST /voids` — Create a void - `GET /voids/{id}` — Get void by ID **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Retrieve a webhook delivery Source: https://docs.revkeen.com/docs/api-reference/webhook_deliveries_get **Related endpoints** - `GET /webhook-deliveries` — List webhook deliveries - `POST /webhook-deliveries/{id}/retry` — Retry a webhook delivery **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- Retrieve the details of a single webhook delivery including its last attempt outcome. --- **Related endpoints** - `GET /webhook-deliveries` — List webhook deliveries - `POST /webhook-deliveries/{id}/retry` — Retry a webhook delivery **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. --- # List webhook deliveries Source: https://docs.revkeen.com/docs/api-reference/webhook_deliveries_list **Related endpoints** - `GET /webhook-deliveries/{id}` — Retrieve a webhook delivery - `POST /webhook-deliveries/{id}/retry` — Retry a webhook delivery **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List individual webhook delivery attempts across all endpoints for the authenticated merchant. Use filters to scope to a specific endpoint, a specific event, or a specific delivery status. Results are returned in reverse chronological order. --- **Related endpoints** - `GET /webhook-deliveries/{id}` — Retrieve a webhook delivery - `POST /webhook-deliveries/{id}/retry` — Retry a webhook delivery **Common errors** - `401 unauthenticated` — missing, malformed, or revoked API key. **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Retry a webhook delivery Source: https://docs.revkeen.com/docs/api-reference/webhook_deliveries_retry **Related endpoints** - `GET /webhook-deliveries` — List webhook deliveries - `GET /webhook-deliveries/{id}` — Retrieve a webhook delivery **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Queue an immediate retry of this delivery. The delivery is marked `pending` and `next_retry_at` is set to now; the dispatcher picks it up on its next tick. Calling retry on an already-pending delivery just advances its retry time. Dead-lettered deliveries can be retried once; succeeded deliveries cannot. --- **Related endpoints** - `GET /webhook-deliveries` — List webhook deliveries - `GET /webhook-deliveries/{id}` — Retrieve a webhook delivery **Common errors** - `404 resource_missing` — the referenced resource does not exist or is not visible to your key. - `409 conflict` — Idempotency-Key collision with a different body, or a concurrent state-transition conflict. **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Create webhook endpoint Source: https://docs.revkeen.com/docs/api-reference/webhook_endpoints_create **Related endpoints** - `GET /webhook-endpoints` — List webhook endpoints - `GET /webhook-endpoints/{id}` — Get webhook endpoint - `PATCH /webhook-endpoints/{id}` — Update webhook endpoint - `DELETE /webhook-endpoints/{id}` — Delete webhook endpoint - `POST /webhook-endpoints/{id}/rotate-secret` — Rotate signing secret **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Create a webhook endpoint to receive event notifications at the given URL. Returns the endpoint with its signing secret — store the secret securely, it is only shown once. --- **Related endpoints** - `GET /webhook-endpoints` — List webhook endpoints - `GET /webhook-endpoints/{id}` — Get webhook endpoint - `PATCH /webhook-endpoints/{id}` — Update webhook endpoint - `DELETE /webhook-endpoints/{id}` — Delete webhook endpoint - `POST /webhook-endpoints/{id}/rotate-secret` — Rotate signing secret **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Delete webhook endpoint Source: https://docs.revkeen.com/docs/api-reference/webhook_endpoints_delete **Related endpoints** - `GET /webhook-endpoints` — List webhook endpoints - `POST /webhook-endpoints` — Create webhook endpoint - `GET /webhook-endpoints/{id}` — Get webhook endpoint - `PATCH /webhook-endpoints/{id}` — Update webhook endpoint - `POST /webhook-endpoints/{id}/rotate-secret` — Rotate signing secret **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Permanently delete a webhook endpoint and all its event subscriptions. --- **Related endpoints** - `GET /webhook-endpoints` — List webhook endpoints - `POST /webhook-endpoints` — Create webhook endpoint - `GET /webhook-endpoints/{id}` — Get webhook endpoint - `PATCH /webhook-endpoints/{id}` — Update webhook endpoint - `POST /webhook-endpoints/{id}/rotate-secret` — Rotate signing secret **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Get webhook endpoint Source: https://docs.revkeen.com/docs/api-reference/webhook_endpoints_get **Related endpoints** - `GET /webhook-endpoints` — List webhook endpoints - `POST /webhook-endpoints` — Create webhook endpoint - `PATCH /webhook-endpoints/{id}` — Update webhook endpoint - `DELETE /webhook-endpoints/{id}` — Delete webhook endpoint - `POST /webhook-endpoints/{id}/rotate-secret` — Rotate signing secret --- Retrieve a single webhook endpoint by ID, including delivery statistics. --- **Related endpoints** - `GET /webhook-endpoints` — List webhook endpoints - `POST /webhook-endpoints` — Create webhook endpoint - `PATCH /webhook-endpoints/{id}` — Update webhook endpoint - `DELETE /webhook-endpoints/{id}` — Delete webhook endpoint - `POST /webhook-endpoints/{id}/rotate-secret` — Rotate signing secret --- # List webhook endpoints Source: https://docs.revkeen.com/docs/api-reference/webhook_endpoints_list **Related endpoints** - `POST /webhook-endpoints` — Create webhook endpoint - `GET /webhook-endpoints/{id}` — Get webhook endpoint - `PATCH /webhook-endpoints/{id}` — Update webhook endpoint - `DELETE /webhook-endpoints/{id}` — Delete webhook endpoint - `POST /webhook-endpoints/{id}/rotate-secret` — Rotate signing secret **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- List all webhook endpoints for the authenticated merchant. Supports filtering by status and pagination. --- **Related endpoints** - `POST /webhook-endpoints` — Create webhook endpoint - `GET /webhook-endpoints/{id}` — Get webhook endpoint - `PATCH /webhook-endpoints/{id}` — Update webhook endpoint - `DELETE /webhook-endpoints/{id}` — Delete webhook endpoint - `POST /webhook-endpoints/{id}/rotate-secret` — Rotate signing secret **Pagination** Offset-based with `limit` (default 25, max 100) and `offset`. The response `pagination` block includes `total` and `hasMore`. See [the pagination guide](/docs/fundamentals/pagination) for SDK auto-paging helpers. --- # Rotate signing secret Source: https://docs.revkeen.com/docs/api-reference/webhook_endpoints_rotate_secret **Related endpoints** - `GET /webhook-endpoints` — List webhook endpoints - `POST /webhook-endpoints` — Create webhook endpoint - `GET /webhook-endpoints/{id}` — Get webhook endpoint - `PATCH /webhook-endpoints/{id}` — Update webhook endpoint - `DELETE /webhook-endpoints/{id}` — Delete webhook endpoint **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Generate a new signing secret for a webhook endpoint. The old secret is immediately invalidated. Store the new secret securely — it is only returned in this response. --- **Related endpoints** - `GET /webhook-endpoints` — List webhook endpoints - `POST /webhook-endpoints` — Create webhook endpoint - `GET /webhook-endpoints/{id}` — Get webhook endpoint - `PATCH /webhook-endpoints/{id}` — Update webhook endpoint - `DELETE /webhook-endpoints/{id}` — Delete webhook endpoint **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Update webhook endpoint Source: https://docs.revkeen.com/docs/api-reference/webhook_endpoints_update **Related endpoints** - `GET /webhook-endpoints` — List webhook endpoints - `POST /webhook-endpoints` — Create webhook endpoint - `GET /webhook-endpoints/{id}` — Get webhook endpoint - `DELETE /webhook-endpoints/{id}` — Delete webhook endpoint - `POST /webhook-endpoints/{id}/rotate-secret` — Rotate signing secret **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- Update a webhook endpoint's URL, subscribed events, description, or enabled status. --- **Related endpoints** - `GET /webhook-endpoints` — List webhook endpoints - `POST /webhook-endpoints` — Create webhook endpoint - `GET /webhook-endpoints/{id}` — Get webhook endpoint - `DELETE /webhook-endpoints/{id}` — Delete webhook endpoint - `POST /webhook-endpoints/{id}/rotate-secret` — Rotate signing secret **Idempotency** Pass an `Idempotency-Key` header (UUID v4 recommended) to make retries safe. Keys are valid for 24 hours; see [the idempotency guide](/docs/fundamentals/idempotency). --- # Security Overview Source: https://docs.revkeen.com/docs/trust How RevKeen protects your data and your customers' data RevKeen is built with security as a foundational requirement, not an afterthought. Every layer of the platform -- from infrastructure to application logic -- is designed to protect your data and your customers' data. ## Security Philosophy RevKeen follows three core security principles: 1. **Defense in depth** -- Multiple independent layers of protection ensure that no single failure compromises your data. 2. **Least privilege** -- Every component, service, and database role operates with the minimum permissions required. 3. **Tenant isolation by default** -- Your data is logically separated from every other merchant on the platform at the database level. ## Infrastructure Overview RevKeen runs on industry-standard cloud infrastructure with encryption enforced at every boundary. | Layer | Provider | Details | |-------|----------|---------| | Application hosting | AWS (eu-west-1) | Fargate containers in private subnets with no direct internet exposure | | Database | Supabase (Frankfurt, EU) | Managed PostgreSQL with automated backups and point-in-time recovery | | Secrets management | Infisical | Encrypted secret storage with audit logging and access controls | | Edge and CDN | Cloudflare / Vercel | DDoS protection, TLS termination, and edge caching | | Background jobs | Trigger.dev Cloud | Isolated task execution for async processing | ### Encryption - **At rest** -- All databases, backups, and object storage are encrypted using AES-256. - **In transit** -- All connections use TLS 1.2 or higher. Internal service-to-service communication is encrypted. - **Secrets** -- API keys, gateway credentials, and sensitive configuration are stored in Infisical with envelope encryption. They are never committed to source control or exposed in logs. ## Tenant Isolation via Row Level Security RevKeen uses PostgreSQL Row Level Security (RLS) to enforce strict tenant isolation at the database layer. This means that even if application code contains a bug, one merchant's data cannot leak to another. Every query that touches merchant-scoped data runs through RLS policies that filter rows by `merchant_id`. This is enforced by the database engine itself -- not by application-layer filtering. - **Runtime role** -- API requests execute as `revkeen_runtime`, which can only access rows matching the authenticated merchant's ID. - **System role** -- Cross-tenant operations (such as scheduled jobs) execute as `revkeen_system` with explicit full-access policies and audit logging. - **Silent deny** -- If the merchant context is missing or incorrect, queries return zero rows rather than raising errors. This eliminates data leakage even in edge cases. For developers building integrations, this means your API keys and tokens are scoped to your merchant account. There is no way to access another merchant's data through the API. ## Security Audits RevKeen conducts regular security reviews across the platform: - **Dependency scanning** -- Automated vulnerability scanning on every pull request via GitHub Actions. - **Infrastructure review** -- Periodic review of AWS IAM policies, network ACLs, and security group configurations. - **Code review** -- All changes to authentication, authorization, and payment flows require review before merging. - **Database policy audits** -- RLS policies are verified against the production schema to detect drift or missing coverage. ## Responsible Disclosure If you discover a security vulnerability in RevKeen, we want to hear from you. Please report it responsibly: - Email **security@revkeen.com** with a description of the vulnerability. - Include steps to reproduce the issue if possible. - Do not publicly disclose the vulnerability until we have had a chance to investigate and deploy a fix. - We commit to acknowledging reports within 48 hours and providing a resolution timeline within 5 business days. We do not pursue legal action against researchers who follow responsible disclosure practices. ## SOC 2 Compliance Roadmap RevKeen is working toward SOC 2 Type II certification. Our current progress: | Control Area | Status | |-------------|--------| | Access controls and authentication | Implemented -- Better Auth with organization-based access | | Data encryption (at rest and in transit) | Implemented -- AES-256 and TLS 1.2+ | | Audit logging | Implemented -- Database and application-level audit trails | | Incident response procedures | Documented and tested | | Vendor risk management | In progress -- third-party processor inventory | | Formal audit engagement | Planned | We will update this page as we reach each milestone. If you have specific compliance questions or need documentation for your own audits, contact **support@revkeen.com**. --- # Data Handling Source: https://docs.revkeen.com/docs/trust/data-handling How RevKeen stores, processes, and protects personal and financial data RevKeen processes personal and financial data on behalf of merchants. This page explains where your data lives, how it is protected, and what controls you have over it. ## Data Storage Locations RevKeen stores data in the European Union to meet GDPR requirements and minimize latency for EU-based operations. | Data Type | Location | Provider | |-----------|----------|----------| | Primary database (merchants, customers, invoices, transactions) | Frankfurt, Germany (eu-central-1) | Supabase (managed PostgreSQL) | | Application services and API | Ireland (eu-west-1) | AWS Fargate | | Background job execution | EU region | Trigger.dev Cloud | | Secrets and credentials | EU region | Infisical | | Static assets and checkout pages | Global edge (origin EU) | Vercel / Cloudflare | | Observability and logs | EU region | Grafana Cloud | No primary data is stored outside the EU. Edge caching of static assets (CSS, JavaScript, images) uses global CDN nodes but does not cache personal or financial data. ## Encryption ### At Rest All data stored by RevKeen is encrypted at rest: - **Database** -- Supabase uses AES-256 encryption for all PostgreSQL data and backups. - **Object storage** -- Files stored in S3 use server-side encryption (SSE-S3 with AES-256). - **Secrets** -- Infisical encrypts all secrets using envelope encryption before storage. ### In Transit All data in transit is encrypted: - **Browser to RevKeen** -- TLS 1.2 or higher on all public endpoints. HSTS headers enforce HTTPS. - **Service to service** -- Internal communication between RevKeen services uses TLS. - **RevKeen to gateway** -- API calls to payment gateways use TLS with certificate validation. - **Database connections** -- All connections to Supabase require SSL. ## GDPR Compliance RevKeen operates as a **data processor** on behalf of merchants (data controllers). Our GDPR commitments: | Principle | How RevKeen Complies | |-----------|---------------------| | **Lawful basis** | RevKeen processes data based on the merchant's contractual relationship with their customers. Merchants are responsible for establishing lawful basis. | | **Data minimization** | RevKeen collects only the data necessary to process payments, generate invoices, and provide the platform's features. | | **Purpose limitation** | Customer data is used only for the merchant's billing and payment operations. RevKeen does not sell or share data with third parties for marketing. | | **Storage limitation** | Data is retained according to configurable retention policies (see below). | | **Right of access** | Merchants can export all customer data through the dashboard or API. | | **Right to erasure** | Merchants can request deletion of customer data, subject to legal retention requirements for financial records. | | **Data portability** | All data is exportable in standard formats via the API. | | **Breach notification** | RevKeen will notify affected merchants within 72 hours of confirming a personal data breach. | A Data Processing Agreement (DPA) is available upon request. Contact **privacy@revkeen.com**. ## Data Retention Policies RevKeen retains data according to the following defaults. Merchants may have additional obligations under local financial regulations. | Data Category | Default Retention | Reason | |---------------|-------------------|--------| | Transaction records | 7 years | Financial record-keeping and tax compliance | | Invoice data | 7 years | Legal requirement for financial documents | | Customer personal data | Duration of merchant account + 90 days | Active use, then cleanup window | | Payment tokens | Until customer or merchant deletes | Required for recurring payments | | Audit logs | 2 years | Security and compliance investigations | | Session data | 30 days | Operational use | | Analytics events | 1 year | Product analytics and checkout optimization | After the retention period, data is permanently deleted. Deletion is irreversible. ## Data Export and Deletion ### Export Merchants can export their data at any time: - **Dashboard** -- Export invoices, transactions, and customer records as CSV from the dashboard. - **API** -- Use the RevKeen API to programmatically retrieve all data associated with your merchant account. Exports include all data RevKeen stores for your account, including customer details, transaction history, invoice records, and subscription data. ### Deletion To request data deletion: - **Individual customer data** -- Delete a customer record through the dashboard or API. Associated personal data is removed, while anonymized transaction records are retained for financial compliance. - **Full account deletion** -- Contact **support@revkeen.com** to request complete deletion of your merchant account and all associated data. This is processed within 30 days. Certain data cannot be deleted before the legally mandated retention period (for example, transaction records required for tax compliance). ## Third-Party Data Processors RevKeen uses the following third-party services that may process your data: | Processor | Purpose | Data Shared | Location | |-----------|---------|-------------|----------| | Supabase | Database hosting | All merchant and customer data | Frankfurt, EU | | AWS | Application hosting, storage | Application data, logs | Ireland, EU | | NMI (or merchant's gateway) | Payment processing | Transaction amounts, tokenized card references | Varies by gateway | | Quaderno | Tax calculation and invoicing | Customer address, transaction amounts | EU | | Novu | In-app notifications | Notification content, subscriber IDs | EU | | Trigger.dev | Background job processing | Job payloads (merchant IDs, task parameters) | EU | | Grafana Cloud | Observability and monitoring | Application logs and metrics (no PII in normal operation) | EU | | Infisical | Secrets management | Encrypted API keys and credentials | EU | RevKeen maintains data processing agreements with all sub-processors. We evaluate each processor's security practices before integration and monitor them on an ongoing basis. ## Secrets Management Sensitive credentials -- such as gateway API keys, webhook signing secrets, and internal service tokens -- are managed through Infisical: - Secrets are encrypted at rest and in transit. - Access is scoped by environment (production, staging, development). - Secret access is logged for audit purposes. - Secrets are injected into services at runtime and are never written to disk or committed to source control. - Rotation is supported without service downtime. If you need to rotate your gateway credentials or API keys, you can do so through the RevKeen dashboard. The change takes effect immediately. --- # PCI Compliance Source: https://docs.revkeen.com/docs/trust/pci-compliance How RevKeen maintains PCI DSS compliance for payment processing RevKeen is designed so that you can accept payments without handling sensitive card data yourself. This page explains how PCI DSS applies to RevKeen and what it means for your business. ## What is PCI DSS? The Payment Card Industry Data Security Standard (PCI DSS) is a set of security requirements that apply to any organization that stores, processes, or transmits cardholder data. It exists to protect customers from fraud and data breaches. PCI compliance is not optional -- if you accept card payments, you must meet the requirements that apply to your level of card data exposure. ## RevKeen's PCI Scope RevKeen minimizes your PCI scope by ensuring that sensitive card data never touches RevKeen's servers or yours. ### How card data flows ``` Customer's browser --> Payment gateway (NMI / processor) --> Card networks | Returns token | RevKeen stores token only ``` 1. The customer enters their card details into RevKeen's hosted checkout or an embedded payment form. 2. Card data is sent directly from the customer's browser to the payment gateway over a TLS-encrypted connection. 3. The gateway processes the card, returns a token (a non-reversible reference), and sends the transaction result. 4. RevKeen stores only the token and masked card details (last four digits, card brand, expiration). The full card number never reaches RevKeen. ### What RevKeen does NOT store - Full card numbers (PAN) - CVV / CVC codes - PIN data - Magnetic stripe data - Full track data ## SAQ-A Eligibility Because RevKeen uses hosted checkout and direct-to-gateway tokenization, merchants using RevKeen's standard checkout are eligible for **SAQ-A** -- the simplest PCI self-assessment questionnaire. SAQ-A applies when: - All payment processing is outsourced to a PCI-compliant service provider. - Your website does not directly receive, transmit, or store cardholder data. - You use a hosted payment page or iframe-based checkout. RevKeen's hosted checkout meets all of these criteria. ## Tokenization Tokenization replaces sensitive card data with a non-sensitive token that has no exploitable value if intercepted. | Data | Stored by RevKeen | Example | |------|-------------------|---------| | Token | Yes | `tok_abc123def456` | | Last four digits | Yes | `4242` | | Card brand | Yes | `Visa` | | Expiration | Yes | `12/2027` | | Full card number | **No** | Never stored | | CVV | **No** | Never stored | Tokens are gateway-specific and cannot be used outside of your authenticated gateway account. Even if a token were exposed, it could not be used to make a payment without your gateway credentials. ## Gateway Handles Card Data Your payment gateway (such as NMI) is a PCI DSS Level 1 certified service provider. The gateway is responsible for: - Receiving and encrypting card data from the customer's browser. - Performing authorization and capture with the card networks. - Storing card-on-file data securely for recurring payments. - Returning tokenized references to RevKeen. RevKeen communicates with the gateway using server-side API calls authenticated with your gateway credentials, which are stored encrypted in Infisical. ## Hosted Checkout Reduces Your PCI Burden RevKeen's hosted checkout is served from RevKeen's domain. This means: - Card fields are rendered by RevKeen, not embedded in your site's DOM. - Your servers never see card data, even transiently. - You do not need to implement or maintain TLS for payment form endpoints. - Your PCI scope is limited to ensuring you use the hosted checkout correctly and do not introduce client-side scripts that intercept card data. If you use RevKeen's hosted checkout without modification, your PCI obligations are minimal. ## What Merchants Need to Do Even with SAQ-A eligibility, you still have responsibilities: | Responsibility | Details | |----------------|---------| | **Complete SAQ-A annually** | A short self-assessment questionnaire confirming you meet the basic requirements. Your payment processor or acquiring bank may provide a portal for this. | | **Use strong passwords** | Ensure your RevKeen account and gateway credentials use strong, unique passwords. Enable two-factor authentication where available. | | **Do not log card data** | Never log, email, or store full card numbers -- even temporarily -- in your own systems. | | **Keep your site secure** | If you embed RevKeen checkout links on your website, ensure your site uses HTTPS and is free of malicious scripts that could intercept form data. | | **Report compromises** | If you suspect a data breach, notify your payment processor and RevKeen immediately. | ## Custom Integrations If you use the RevKeen API to build a custom checkout experience instead of the hosted checkout, your PCI scope may increase. Specifically: - If card data passes through your servers before reaching the gateway, you may need to complete **SAQ-D** (the most comprehensive assessment). - If you use direct post or iframe-based integration where card data goes directly to the gateway, **SAQ-A-EP** may apply. Contact your acquiring bank or a Qualified Security Assessor (QSA) if you are unsure which SAQ applies to your integration. --- # Uptime and Reliability Source: https://docs.revkeen.com/docs/trust/uptime RevKeen's infrastructure, redundancy, and uptime commitments RevKeen is built on infrastructure designed for high availability. This page covers how we keep the platform running, what happens when things go wrong, and what uptime you can expect. ## Infrastructure Overview RevKeen's core services run on AWS in the `eu-west-1` (Ireland) region, with the primary database hosted on Supabase in Frankfurt (EU). | Component | Technology | Availability Design | |-----------|-----------|-------------------| | API and application server | AWS Fargate (ECS) | Multiple containers across availability zones | | Database | Supabase managed PostgreSQL | Automated backups, point-in-time recovery | | Background jobs | Trigger.dev Cloud | Managed execution with automatic retries | | Edge and CDN | Cloudflare / Vercel | Global edge network with automatic failover | | Real-time messaging | Upstash Redis | Managed Redis with replication | | DNS | Cloudflare | Anycast DNS with DDoS protection | ### Multi-AZ Deployment RevKeen's Fargate services run across multiple AWS Availability Zones. If one AZ experiences an outage, traffic is automatically routed to healthy containers in other zones. There is no single point of failure at the application tier. ### Auto-scaling Application containers scale automatically based on CPU and memory utilization. During traffic spikes -- such as a large batch of invoices being sent -- additional containers are launched to handle the load without degrading response times. ## Database Reliability RevKeen's primary database is hosted on Supabase's managed PostgreSQL platform: - **Automated daily backups** with configurable retention. - **Point-in-time recovery (PITR)** allows restoring the database to any second within the retention window. - **Connection pooling** via Supabase's built-in PgBouncer ensures stable performance under high connection counts. - **Read replicas** can be provisioned for read-heavy workloads without impacting write performance. Database maintenance (such as PostgreSQL version upgrades) is managed by Supabase with minimal downtime, typically during low-traffic windows. ## Status Page RevKeen publishes real-time platform status and historical uptime at: **[status.revkeen.com](https://status.revkeen.com)** The status page shows: - Current operational status for all services (API, dashboard, checkout, webhooks). - Active and resolved incidents with timestamps and impact descriptions. - Scheduled maintenance windows. - Historical uptime metrics. You can subscribe to status updates via email or RSS to receive notifications when incidents are reported or resolved. ## Incident Response When an issue is detected, RevKeen follows a structured incident response process: ### Detection Incidents are detected through multiple channels: - **Automated monitoring** -- Grafana alerts on error rates, latency spikes, and infrastructure anomalies. - **Synthetic checks** -- Periodic health checks against critical endpoints (API, checkout, webhooks). - **Customer reports** -- Issues reported through support channels. ### Response Timeline | Severity | Definition | Response Target | Update Frequency | |----------|-----------|----------------|-----------------| | **Critical** | Payment processing or checkout is unavailable | 15 minutes | Every 30 minutes | | **High** | Major feature degraded (dashboard, webhooks) | 30 minutes | Every hour | | **Medium** | Non-critical feature impacted | 2 hours | As progress is made | | **Low** | Minor issue, no customer impact | Next business day | On resolution | ### Process 1. **Acknowledge** -- The on-call engineer acknowledges the alert and begins investigation. 2. **Communicate** -- A status page update is posted describing the issue and estimated impact. 3. **Mitigate** -- The immediate priority is restoring service, even if the root cause is not yet identified. 4. **Resolve** -- The underlying issue is fixed and verified. 5. **Review** -- A post-incident review identifies root cause, contributing factors, and preventive measures. Post-incident reviews for Critical and High severity incidents are shared with affected merchants upon request. ## Planned Maintenance RevKeen schedules maintenance windows to minimize disruption: - **Routine maintenance** is performed during low-traffic periods, typically weekday mornings (UTC). - **Advance notice** is provided at least 48 hours before any maintenance that may cause downtime. - **Zero-downtime deployments** are the default for application updates. New containers are started and verified before old containers are drained. - **Database maintenance** follows Supabase's managed upgrade process, which typically involves seconds of downtime rather than minutes. Scheduled maintenance is announced on the status page and via email to account administrators. ## SLA Overview RevKeen targets the following service levels: | Metric | Target | |--------|--------| | API availability (monthly) | 99.9% | | Checkout availability (monthly) | 99.9% | | Webhook delivery (first attempt) | Within 30 seconds of event | | Webhook delivery (with retries) | Within 24 hours, with exponential backoff | | Dashboard availability | 99.5% | | Planned maintenance downtime | Less than 1 hour per month | Availability is measured as the percentage of time the service responds to valid requests with non-error responses, excluding scheduled maintenance windows. For merchants on enterprise plans, custom SLAs with financial commitments are available. Contact **sales@revkeen.com** for details. ## What Happens During an Outage If RevKeen experiences downtime, here is what you can expect: - **Checkout** -- If the checkout service is unavailable, customers will see an error page. No partial charges will be created. - **Webhooks** -- Events that occur during an outage are queued and delivered with retries once service is restored. You will not miss events. - **Subscriptions** -- Renewal attempts that fail due to a RevKeen outage are automatically retried. No subscriptions are cancelled due to platform downtime. - **Dashboard** -- The dashboard may be temporarily unavailable, but no data is lost. All transactions continue to be recorded and will appear once the dashboard is restored. --- # Guides Source: https://docs.revkeen.com/docs/guides Step-by-step guides to help you get the most out of RevKeen. Practical walkthroughs for common tasks. Each guide takes you from start to finish with clear steps and working examples. ## Getting Started - **Account Setup**: Create your merchant account and configure your organization. - **Gateway Configuration**: Connect your NMI payment gateway and start processing. - **Developer Quickstart**: API keys, SDKs, and your first API call. ## Billing - **Subscriptions**: Create and manage recurring billing plans. - **Usage-Based Billing**: Set up metered billing with usage events and meters. - **Dunning**: Configure automatic payment recovery for failed charges. - **Invoices & Orders**: Generate, send, and track invoices. ## Payments - **Accept Payments**: Process card payments, refunds, and voids. - **Checkout**: Embed hosted checkout pages and payment links. - **Customer Portal**: Let customers manage their own billing. ## Integrations - **Quaderno Tax**: Automate tax compliance with Quaderno. - **Webhooks**: Receive real-time event notifications. - **Zapier**: Connect RevKeen to 5,000+ apps. --- # RevKeen MCP Source: https://docs.revkeen.com/docs/mcp Connect RevKeen billing tools to AI hosts over the Model Context Protocol RevKeen MCP lets AI hosts like Claude, Cursor, and VS Code query your billing, customer, subscription, and usage data through the [Model Context Protocol](https://modelcontextprotocol.io) — an open standard for connecting AI assistants to external tools securely. On this page you will learn how to connect your AI host to RevKeen, what tools are available, how the scope-based access model works, and when to choose MCP over SDKs or the REST API. ## Quick start The fastest path: one command in your terminal. ```bash claude mcp add --transport http revkeen https://mcp.revkeen.com/mcp ``` RevKeen opens a browser-based OAuth flow. Grant the scopes you need and you are connected. Try asking: > _"List all overdue invoices from the last 30 days"_ --- ## Connect from other hosts If you are not using Claude Code, pick your host below and add the configuration. ```json // .cursor/mcp.json in your project root { "mcpServers": { "revkeen": { "url": "https://mcp.revkeen.com/mcp" } } } ``` ```json // .vscode/mcp.json in your project root { "servers": { "revkeen": { "type": "http", "url": "https://mcp.revkeen.com/mcp" } } } ``` ```json // claude_desktop_config.json { "mcpServers": { "revkeen": { "command": "npx", "args": ["-y", "@anthropic-ai/mcp-remote", "https://mcp.revkeen.com/mcp"] } } } ``` ```text Server URL: https://mcp.revkeen.com/mcp Transport: Streamable HTTP Authentication: OAuth 2.1 (browser flow) ``` After your host connects, RevKeen opens a browser-based OAuth flow. The granted scopes become the tool permissions for that session. ## Example prompts Once connected, try these prompts in your AI host to see what RevKeen MCP can do: | Prompt | What it uses | |--------|-------------| | _"List all overdue invoices from the last 30 days"_ | `invoices_list` with status filter | | _"Show me the details for customer Jane Smith"_ | `customers_list` (search) then `customers_get` | | _"Which subscriptions are currently in dunning?"_ | `subscriptions_list_in_dunning` | | _"What is the total usage for meter X this billing period?"_ | `usage_events_aggregate` | | _"Show me all payments over $500 this month"_ | `payments_list` with amount filter | | _"Check the usage balance for subscription abc-123"_ | `usage_balance_get` | | _"List all active subscriptions for customer def-456"_ | `subscriptions_list` with customer filter | | _"Dry-run a usage event to validate my payload"_ | `usage_events_dry_run` | Your AI host translates these into the appropriate tool calls automatically. ## Available tools The default profile exposes **20 read-only tools** across eight areas. Write operations are behind a separate rollout policy. ### Customers | Tool | Description | Parameters | |------|-------------|------------| | `customers_list` | List customers with optional search and pagination | `search` (string), `limit` (1-100), `offset` | | `customers_get` | Retrieve a single customer by UUID | `id` (required) | ### Invoices | Tool | Description | Parameters | |------|-------------|------------| | `invoices_list` | List invoices with optional status and customer filters | `status`, `customerId`, `limit` (1-100), `offset` | | `invoices_get` | Retrieve a single invoice with line items, taxes, and terms | `id` (required) | ### Payments | Tool | Description | Parameters | |------|-------------|------------| | `payments_list` | List payment transactions for the merchant | `limit`, `offset` | | `payments_get` | Retrieve a single payment transaction by ID | `id` (required) | ### Orders | Tool | Description | Parameters | |------|-------------|------------| | `orders_list` | List orders with line items and fulfillment status | `limit`, `offset` | | `orders_get` | Retrieve a single order by ID | `id` (required) | ### Subscriptions | Tool | Description | Parameters | |------|-------------|------------| | `subscriptions_list` | List subscriptions with status and customer filters | `status` (active, canceled, past_due, trialing, paused), `customerId`, `page`, `limit` (1-100) | | `subscriptions_get` | Retrieve a single subscription with full billing terms | `id` (required) | | `subscriptions_list_in_dunning` | List subscriptions currently in payment recovery with retry and attempt metadata | None | ### Meters and pricing | Tool | Description | Parameters | |------|-------------|------------| | `meters_list` | List usage meters with event names, aggregation types, and filters | None | | `meters_get` | Retrieve a single meter with full filter configuration | `id` (required) | | `meters_list_prices` | List price tiers for a meter including unit price and aggregation granularity | `meterId` (required) | ### Usage billing | Tool | Description | Parameters | |------|-------------|------------| | `usage_events_list` | List recorded usage events with optional meter and time range filters | `meter_id`, `subscription_id`, time range | | `usage_events_aggregate` | Aggregate usage events by sum, count, or average across dimensions | Aggregation function, grouping dimensions | | `usage_events_dry_run` | Validate a usage event payload without recording it — safe for testing | Usage event payload | | `usage_balance_get` | Get current usage balance and allowance for a subscription or customer | `subscription_id`, `customer_id`, `external_customer_id`, `meter_id` | ### Integrations | Tool | Description | Parameters | |------|-------------|------------| | `integrations_list_packages` | List available integration packages and their connection statuses | None | | `integrations_list_mappings` | List product and field mappings between RevKeen and external systems | None | > **Note:** All 20 tools are **read-only**. Write and destructive operations (create, update, delete, send) are not exposed in the default profile. RevKeen is rolling these out behind a separate policy as the tool contract stabilizes. ## Scope model Access is controlled through eight read-focused OAuth scopes. Each scope unlocks specific tools. When you connect, the OAuth consent screen lets you choose which scopes to grant. | Scope | What it unlocks | |------|------------------| | `customers:read` | `customers_list`, `customers_get` | | `invoices:read` | `invoices_list`, `invoices_get` | | `payments:read` | `payments_list`, `payments_get` | | `orders:read` | `orders_list`, `orders_get` | | `subscriptions:read` | `subscriptions_list`, `subscriptions_get`, `subscriptions_list_in_dunning` | | `prices:read` | `meters_list`, `meters_get`, `meters_list_prices` | | `usage:read` | `usage_events_list`, `usage_events_aggregate`, `usage_events_dry_run`, `usage_balance_get` | | `integrations:read` | `integrations_list_packages`, `integrations_list_mappings` | If your AI host connects but tools are missing, check that you granted the right scopes during OAuth. ## How access works ### Your host connects Your MCP host sends a connection request to `https://mcp.revkeen.com/mcp` using Streamable HTTP transport. ### OAuth consent in your browser RevKeen redirects you to a browser-based OAuth 2.1 consent screen. You sign in with your RevKeen account and select which scopes (customers, invoices, payments, etc.) to grant for this session. ### Scoped session created RevKeen issues a session token scoped to your merchant and the approved scopes. The token is bound to the MCP session and cannot be reused outside the host. ### Tool calls enforced server-side Every tool call is checked against your scopes, merchant isolation, and rate limits. The server enforces access policy, audit logs every call, scrubs PII from responses, and manages the session lifecycle for you. This is the key difference between MCP and handing an AI tool a raw API key. The MCP server enforces access boundaries, tenant isolation, and tool contracts — the AI host cannot bypass them. ## Tool stability The 20 v1 tools are stable. RevKeen follows these guarantees: - **No breaking changes** to existing tool names, required parameters, or response shapes within a version. - **New tools** are added behind rollout policies and announced in the [changelog →](/docs/changelog). - **Deprecations** are communicated with at least 90 days notice before removal. - **Write tools** will be introduced incrementally with explicit opt-in. You can build automation on top of the v1 tool contract with confidence. ## Rate limits The MCP server enforces per-session rate limits to protect merchant resources: | Scope | Limit | |-------|-------| | Per session | 60 requests per minute | | Per merchant | 300 requests per minute (across all sessions) | If you exceed a rate limit, the server returns an error with a `retry_after` hint. Wait the indicated time before retrying. > **Note:** Rate limits are enforced server-side with Redis-backed counters. In production, rate limiting uses a fail-closed model — if the rate limit backend is unavailable, requests are denied rather than allowed. ## Operational endpoints | Endpoint | Purpose | |----------|---------| | `https://mcp.revkeen.com/` | Root metadata and public server information | | `https://mcp.revkeen.com/healthz` | Health check (returns `200 OK` when healthy) | | `https://mcp.revkeen.com/mcp` | Remote MCP endpoint (Streamable HTTP) | ## Troubleshooting ### Host cannot connect - Confirm the URL is `https://mcp.revkeen.com/mcp` — not an older SSE or stdio endpoint. - Check that your host supports Streamable HTTP transport. Claude Desktop requires the `@anthropic-ai/mcp-remote` bridge (see setup above). - Verify your network allows outbound HTTPS to `mcp.revkeen.com`. ### OAuth window does not open - Check for browser popup blockers — the OAuth flow opens in a new browser tab. - If you are behind a corporate proxy, ensure `mcp.revkeen.com` and your OAuth provider are allowlisted. - Try disconnecting and reconnecting in your host to re-trigger the flow. ### Connected but tools are missing - Reconnect with the scopes you actually need. If you only granted `customers:read`, invoice tools will not appear. - Some hosts cache the tool list. Try reloading or restarting the host after reconnecting. ### Tool call returns 403 - The authenticated user may not have access to the target merchant. Verify your RevKeen account has the correct merchant role. - Check that the tool's required scope was granted during OAuth. ### Tool call returns rate limit error - Wait for the `retry_after` period indicated in the error response. - If you are running automated workflows, add backoff logic between tool calls. - The per-merchant limit (300/min) is shared across all sessions — coordinate with teammates if multiple people are connected. ### Data looks stale or empty - MCP reads live data from RevKeen. If results are empty, verify the merchant has the expected data in the [RevKeen Dashboard](https://app.revkeen.com). - The MCP server does not cache business data between calls. ## When to use MCP vs SDKs vs REST vs CLI | Surface | Best for | Tradeoffs | |---------|----------|-----------| | [MCP →](/docs/mcp) | AI hosts and agent workflows — natural language queries, copilot integrations | Read-only today, scope-limited, requires OAuth | | [SDKs →](/docs/sdks) | Application code you own and deploy — type-safe, full API coverage | Requires API key management, no AI-native features | | [API Reference →](/docs/api-reference) | Raw HTTP integrations, webhook receivers, protocol details | Most flexible but most manual | | [CLI →](/docs/cli) | Terminal workflows, operator scripts, quick lookups | Best for humans, not for code | > **Note:** If you are building an AI agent that needs to take actions (create invoices, process refunds), use the [REST API →](/docs/api-reference) with an API key today. MCP write tools are coming soon. ## Self-hosting and local development For contributors or advanced local development, you can run the MCP server from the RevKeen monorepo: ```bash pnpm --filter @revkeen/mcp-server dev ``` The local server at `apps/mcp-server` uses the official MCP SDK with the same Streamable HTTP transport, OAuth bearer-token verification, scoped tool access, launch-policy model, and rate limiting as production. ## See also - **API Reference**: The canonical REST contract behind the broader platform. - **SDKs**: Use the official clients for application code you own and deploy. - **OAuth 2.1**: Understand the OAuth model used by MCP and third-party integrations. - **MCP Protocol**: Learn more about the Model Context Protocol standard. --- # Errors Source: https://docs.revkeen.com/docs/errors Error envelope, status codes, and retry guidance for the RevKeen API The RevKeen API returns errors in a consistent envelope with a machine-readable `code`, a human-readable `message`, and — where applicable — the offending `param` and structured field-level `details`. Reserve the `message` for display and the `code` for branching logic. > **Note:** Non-`2xx` status codes always return an `error` object. Inspect `error.code` before `error.message` when writing retry or recovery logic. ## Error envelope ```json { "error": { "type": "invalid_request_error", "code": "validation_error", "message": "Customer email is required.", "param": "customer.email", "details": { "fields": { "customer.email": ["must be a valid email address"] } } } } ``` | Field | Type | Present on | Purpose | |--------------------|-------------------------|------------------------|---------------------------------------------------------------------------------------------------| | `error.type` | `string` (enum) | All errors | Broad category: `invalid_request_error`, `authentication_error`, `permission_error`, etc. | | `error.code` | `string` (enum) | All errors | Stable machine-readable identifier. Safe for logic branching. | | `error.message` | `string` | All errors | Human-readable description. Content may change; do not parse. | | `error.param` | `string` | Validation errors | Dotted path of the offending parameter. | | `error.details` | `object` | Validation errors | Structured extras — most commonly `details.fields[param] = [reasons]`. | ## HTTP status codes | Status | Meaning | When you see it | |-------:|------------------------|---------------------------------------------------------------------------------------------| | `400` | Invalid request | Malformed JSON, unknown fields, failed validation. Do not retry without fixing the payload. | | `401` | Unauthenticated | Missing, malformed, or revoked API key. | | `403` | Permission denied | Key is valid but lacks the required scope, or the resource belongs to a different merchant. | | `404` | Not found | Resource does not exist, or is not visible to your API key. | | `409` | Conflict | Idempotency-Key collision with a different body, or a concurrent state-transition conflict. | | `422` | Unprocessable entity | Business-rule failure (for example, refunding more than the original charge). | | `429` | Rate limit exceeded | Back off using the `Retry-After` header. | | `500` | Server error | Transient — retry with exponential backoff. | | `503` | Service unavailable | Capacity issue — retry with exponential backoff. | ## Retry guidance | Status / Condition | Retryable? | Strategy | |-----------------------------------------|-----------:|--------------------------------------------------------------------------------------------| | `500`, `502`, `503`, `504` | Yes | Exponential backoff, at least 3 attempts, capped at ~30s total. | | `429` | Yes | Honour the `Retry-After` header (seconds). Do not retry sooner. | | Network timeout on a mutation | Yes | Retry with the **same** `Idempotency-Key` — see [Idempotency](./idempotency). | | `400`, `404`, `422` | No | Permanent — fix the payload or resource first. | | `401`, `403` | No | Rotate or rescope the API key, then retry. | | `409` (idempotency conflict) | No | The key was reused with a different body. Generate a new key. | ## Validation errors Validation errors (`type: invalid_request_error`, `code: validation_error`) always include a `details.fields` map. Keys are dotted parameter paths; values are arrays of reasons. ```json { "error": { "type": "invalid_request_error", "code": "validation_error", "message": "One or more fields are invalid.", "details": { "fields": { "items[0].quantity": ["must be greater than 0"], "customer.email": ["must be a valid email address"] } } } } ``` Render field errors next to the offending input rather than surfacing `message` alone. ## Rate-limit errors `429 Too Many Requests` responses always include a `Retry-After` header in seconds: ```http HTTP/1.1 429 Too Many Requests Retry-After: 12 Content-Type: application/json { "error": { "type": "rate_limit_error", "code": "rate_limit_exceeded", "message": "Too many requests." } } ``` Published plan limits are on the [rate limits reference](/docs/fundamentals/rate-limits). ## Examples ```bash curl -i https://staging-api.revkeen.com/v2/customers/cus_does_not_exist \ -H "x-api-key: $REVKEEN_API_KEY" # HTTP/1.1 404 Not Found # { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "Customer not found." } } ``` ```ts const client = new RevKeen({ apiKey: process.env.REVKEEN_API_KEY! }); try { await client.customers.retrieve("cus_does_not_exist"); } catch (err) { if (err instanceof RevKeenError) { if (err.code === "resource_missing") { // permanent — do not retry } } throw err; } ``` ```go _, err := client.Customers.Retrieve(ctx, "cus_does_not_exist") if rkErr, ok := revkeen.AsError(err); ok { if rkErr.Code == "resource_missing" { // permanent — do not retry } } ``` ```php use RevKeen\RevKeenClient; use RevKeen\Exception\RevKeenException; $client = new RevKeenClient(['api_key' => getenv('REVKEEN_API_KEY')]); try { $client->customers->retrieve('cus_does_not_exist'); } catch (RevKeenException $e) { if ($e->getCode() === 'resource_missing') { // permanent — do not retry } throw $e; } ``` ## See also - **Idempotency** (/docs/fundamentals/idempotency): Retry mutations safely with an `Idempotency-Key`. - **Pagination** (/docs/fundamentals/pagination): Iterate over list responses correctly. - **Versioning** (/docs/fundamentals/versioning): Pin the API version with the `RevKeen-Version` header. - **API Reference** (/docs/api-reference): Browse all endpoints and response schemas. --- # Glossary Source: https://docs.revkeen.com/docs/glossary Canonical definitions for terms used across RevKeen documentation ## A ### ACH Automated Clearing House. A US bank transfer network used for direct debit payments. ### ARR (Annual Recurring Revenue) The annualized value of all active subscriptions. Calculated as MRR x 12. ## B ### Billing Interval The frequency at which a subscription is billed (weekly, monthly, quarterly, annually). ## C ### Card on File (COF) A payment method stored securely for future use. RevKeen stores a gateway token, never raw card numbers. See also: **MIT**, **Tokenization**. ### Chargeback A payment reversal initiated by the cardholder's bank. In RevKeen, chargebacks appear as **disputes**. See [Disputes](/docs/using-revkeen/disputes). ### Checkout Link A shareable URL that opens a hosted payment page. Created from a product + price combination. ### Checkout Session A temporary session created when a customer begins the checkout process. Contains product, price, and customer details. ### Collect.js NMI's hosted payment field library that tokenizes card data client-side. Ensures raw card numbers never touch RevKeen servers. ### Connector The Tauri desktop application that bridges RevKeen Cloud and PAX terminal devices for in-person payments. See [Terminal](/docs/using-revkeen/terminal). ### Credit Note A document issued to reduce the amount owed on an invoice. Can trigger a refund, void, or account credit. ### Customer Portal A hosted web application where customers can manage subscriptions, view invoices, and update payment methods. See [Customer Portal](/docs/using-revkeen/customer-portal). ## D ### Decline Code A numeric code returned by the payment gateway explaining why a transaction was rejected. Used by dunning to classify hard vs soft declines. ### Dunning The process of recovering failed subscription payments through automated retries, email reminders, and escalation. See [Dunning](/docs/using-revkeen/dunning). ### Dispute A formal challenge to a payment, typically initiated by the cardholder's bank. RevKeen tracks dispute lifecycle from open through resolution. See [Disputes](/docs/using-revkeen/disputes). ## E ### Elavon A global payment processor (acquirer) that provides the underlying payment rails for RevKeen transactions. ## G ### Gateway A payment processor that handles the actual card transaction. RevKeen is gateway-agnostic and currently supports NMI and Elavon. ### Grace Period The number of days a subscription retains access after a payment fails, while retries are in progress. ## H ### Health Score A 0-100 composite score measuring a customer's payment reliability. Based on punctuality, dunning depth, failure rate, tenure, and method health. See [Customer Health Scores](/docs/using-revkeen/customer-health-scores). ## I ### Idempotency The property of an operation that produces the same result whether executed once or multiple times. Critical for payment operations to prevent double charges. ### Interchange Fee The fee charged by the cardholder's bank on each transaction. Part of the total processing cost visible in margin tracking. ### Invoice A payment request sent to a customer. Contains line items, tax calculations, and payment terms. See [Invoices](/docs/using-revkeen/invoices-and-orders). ## M ### Margin Intelligence RevKeen's unique capability to track all costs (processing, gateway, refunds, chargebacks) and attribute them per transaction, customer, and product. ### Merchant A business using RevKeen to collect payments. Each merchant has isolated data, settings, and API keys. ### Meter A usage-based billing construct that tracks consumption events. Meters aggregate usage and generate invoices based on configured pricing tiers. ### MIT (Merchant-Initiated Transaction) A transaction initiated by the merchant without the cardholder present, using a stored card on file. Subscription renewals are MIT transactions. ### MRR (Monthly Recurring Revenue) The normalized monthly value of all active subscriptions. The primary metric for subscription businesses. ## N ### NMI Network Merchants Inc. The payment gateway used by RevKeen to process card transactions. ## P ### Payment Link See **Checkout Link**. ### Payment Method A stored means of payment (card, bank account) associated with a customer. RevKeen stores gateway tokens, not raw credentials. ### Price A specific pricing configuration for a product. A product can have multiple prices (e.g., monthly and annual). ### Product A sellable item in RevKeen. Products have a billing type (one-time, recurring, usage) and fulfillment type (service, digital, physical). ### Proration Adjusting charges when a subscription changes mid-billing-cycle. For example, upgrading from a $10/mo to $20/mo plan mid-month charges the difference. ## S ### Settlement The process of transferring captured funds from the payment gateway to the merchant's bank account. ### SSE (Server-Sent Events) The transport used for real-time updates from RevKeen to the dashboard. One-way server-to-browser push. ### Subscription A recurring billing relationship between a merchant and customer. Defined by a product, price, billing interval, and payment method. ## T ### Tokenization Replacing sensitive payment data (card numbers) with a non-sensitive token. The gateway stores the real data; RevKeen only stores the token. ### Transaction A financial movement in RevKeen. Sales, refunds, voids, and disputes are all transaction types stored in the unified transaction model. ## U ### Unkey The API key management service used by RevKeen to issue, scope, and rate-limit API keys. ## V ### Vault The secure storage of payment methods. RevKeen's vault stores gateway tokens, not raw card data. See [PCI Compliance](/docs/trust/pci-compliance). ### Void Canceling a transaction before it settles. Unlike a refund, a void prevents the charge from ever appearing on the customer's statement. ## W ### Webhook An HTTP callback triggered by events in RevKeen (payment completed, subscription canceled, etc.). See [Webhooks](/docs/webhooks). --- # Changelog Source: https://docs.revkeen.com/docs/changelog Recent updates, new features, and improvements to the RevKeen platform. Stay up to date with everything we ship. Major releases are announced on our blog — this page covers the full history. --- ## March 2026 ### AI Copilot — Proactive Intelligence & Margin Tools - **53 MCP tools** now available for AI agents to manage billing operations - Proactive alerts for margin drops, churn risk, and dunning opportunities - Natural language queries across invoices, subscriptions, and revenue data - Full-page chat interface in dashboard with visual output ### Marketing Site Rework - 5 new product pages: Payments, Billing, Intelligence, Platform, Future - Interactive savings calculator on homepage and pricing page - PostHog page view and CTA tracking across all pages ### Search & Indexing - Full-text search indexing for customers, invoices, and products - Background indexing via cron-worker with BullMQ queue --- ## February 2026 ### clientId → merchantId Rename - Standardised internal naming: `clientId` → `merchantId` across 8 database tables - Checkout context updated: `CheckoutContext.client` → `.merchant` - Migration `20260208200000` applied to production ### Customer Health Scores - AI-powered health scoring (0–100) for every customer - Factors: payment history, engagement, revenue trend, dispute rate - Health score column added to customer list and detail views --- ## January 2026 ### Usage-Based Billing - Meter creation and usage event ingestion API - Support for sum, count, max, and unique aggregation types - Usage-based line items on invoices with configurable billing periods ### Terminal Payments — PAX A920 - Full POS connector architecture: Cloud ↔ Tauri Connector ↔ PAX Terminal - Device registration, pairing, and heartbeat monitoring - In-person sale, refund, and void operations via dashboard and API - Real-time payment status via SSE --- ## December 2025 ### Platform Launch - Engine-API on AWS ECS Fargate (Frankfurt) - PostgreSQL 18 on RDS with row-level security - Dashboard and Checkout on Vercel (global edge) - Cron-worker and background services on Hetzner ### Core Billing Engine - Products with one-time, recurring, and usage-based pricing - Subscription lifecycle: trials, grace periods, proration, cancellation - Invoice pipeline: draft → open → finalized → paid - AI-powered dunning with configurable retry schedules ### Payment Processing - NMI gateway integration with gateway-agnostic adapter layer - Card-on-file and merchant-initiated transaction compliance - Open banking (Pay-by-Bank) at 0.5% per transaction - Unified transaction model: sale, refund, void, capture, dispute ### Developer Tools - REST API with 50+ endpoints under `/v2/*` - TypeScript, Python, and PHP SDKs - 76 webhook event types with signature verification - Interactive API playground powered by fumadocs-openapi - MCP server for AI agent billing automation ### Integrations - PracticeHub (patients, packages, appointments sync) - Xero and QuickBooks accounting sync - Slack notifications - Quaderno tax automation ---