> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bachs.io/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Money is always a decimal string at the currency's precision (for example "29.00"), paired with an ISO 4217 currency field. Never use minor units.
> Build against the sandbox first: base URL https://sandbox-api.bachs.io with sk_sandbox_ keys. Production is https://api.bachs.io with sk_live_ keys; going live is a key swap.
> Treat webhooks (for example collection.succeeded) as the source of truth for fulfilment, never client-side events or redirects.
> Subscriptions are created by completing a checkout for a recurring product. There is no direct create-subscription endpoint.
> IDs carry resource prefixes (cust_, prod_, sub_, chk_, inv_, ref_) and timestamps are ISO 8601 UTC.
# Bachs skill
> Install the Bachs skill once, and your AI coding assistant follows the Bachs rules on every task: payments, subscriptions, marketplaces and pre-launch reviews.
A **skill** is a file of instructions that your AI coding assistant reads before it writes code. The Bachs skill tells assistants such as Claude Code, Cursor, GitHub Copilot and Codex which Bachs docs to read, which mistakes to avoid, and how to test the result in the sandbox.
You install it once per project. After that, describe what you want, for example "add subscriptions to this app", and your assistant follows the Bachs rules without you pasting them in.
**Don't use skills?** You don't need them. The [prompts](/build/ai/prompts) carry the same guidance as copy-paste text, and you can [paste the skill into any chat](#install).
## Skill or prompt?
| | Prompts | Skill |
| - | - | - |
| Setup | None | One command per project |
| Best for | A single task, or trying Bachs for the first time | Building and maintaining a Bachs integration over time |
| How you use it | Copy the prompt for your task | Describe your task in your own words |
| Covers | One-time payments, subscriptions and a pre-launch review. The marketplace prompt is on its [use case page](/build/use-cases/marketplace#build-it-with-an-ai-assistant). | All four jobs below |
## What the skill does
| Job | What your assistant builds or checks |
| - | - |
| One-time payments | Hosted checkout, order fulfilment from verified webhooks |
| SaaS subscriptions | Plans, access from subscription state, the customer portal |
| Marketplace payments | Seller accounts with Connect, the platform fee, seller payouts |
| Review before go-live | A report of problems by file and line, without changing code |
## Install
Run the command for your tool from your project's root folder.
Install the skill as a plugin, so you can update it later with one command:
```text Claude Code theme={"dark"}
/plugin marketplace add bachsdev/bachs-skills
/plugin install bachs@bachs
```
Or save the file into your project:
```bash Terminal theme={"dark"}
curl -fsSL --create-dirs -o .claude/skills/bachs/SKILL.md https://raw.githubusercontent.com/bachsdev/bachs-skills/main/skills/bachs/SKILL.md
```
Cursor reads skills from the same folder as Claude Code:
```bash Terminal theme={"dark"}
curl -fsSL --create-dirs -o .claude/skills/bachs/SKILL.md https://raw.githubusercontent.com/bachsdev/bachs-skills/main/skills/bachs/SKILL.md
```
Copilot reads skills from the same folder as Claude Code:
```bash Terminal theme={"dark"}
curl -fsSL --create-dirs -o .claude/skills/bachs/SKILL.md https://raw.githubusercontent.com/bachsdev/bachs-skills/main/skills/bachs/SKILL.md
```
```bash Terminal theme={"dark"}
curl -fsSL --create-dirs -o .agents/skills/bachs/SKILL.md https://raw.githubusercontent.com/bachsdev/bachs-skills/main/skills/bachs/SKILL.md
```
1. Download `bachs-skill.zip` from the [latest release](https://github.com/bachsdev/bachs-skills/releases/latest).
2. In Claude, open your skills settings and upload the zip.
3. Turn the skill on.
Open the [skill file](https://raw.githubusercontent.com/bachsdev/bachs-skills/main/skills/bachs/SKILL.md), copy all of it, and paste it at the start of your conversation, before you describe your task.
On Windows, run the commands in PowerShell with `curl.exe` instead of `curl`.
## Use it
Describe what you want to build. Your assistant loads the skill when the task is about Bachs:
```text Example theme={"dark"}
Add Bachs subscriptions to this app, with monthly and yearly plans.
```
```text Example theme={"dark"}
Review our Bachs integration before we go live.
```
In Claude Code you can also call it directly: `/bachs` when you saved the file, or `/bachs:bachs` when you installed the plugin.
Keep your sandbox API key in your server's environment. Never paste it into a chat.
## Update
* **Claude Code plugin:** run `/plugin marketplace update bachs`.
* **Saved file:** run the install command again.
The [changelog](https://github.com/bachsdev/bachs-skills/blob/main/CHANGELOG.md) lists what changed in each version.
## What the skill says
The skill is plain Markdown. This is the current version from the [bachs-skills repository](https://github.com/bachsdev/bachs-skills):
```md SKILL.md theme={"dark"}
---
name: bachs
description: Build Bachs payment integrations (one-time checkout, SaaS subscriptions, marketplace payments with Connect) or review an existing Bachs integration before go-live. Use for checkout, webhook handling, billing access, seller onboarding, testing these flows, and pre-launch reviews.
---
# Build with Bachs
Implement the requested Bachs flow in the user's existing app. Use the current
docs for API fields, product availability, and account requirements.
## Understand the app
Read project instructions and existing authentication, order or billing records,
payment code, and tests. Reuse the app's framework and data layer.
Establish the requested flow, currency, product or plan, and account ownership.
Ask only for missing decisions that affect implementation. Explain the proposed
flow briefly, then carry out the authorized work.
## Read the relevant workflow
Read the selected guide and the references needed for the task. If web access
is unavailable, ask the user to paste the pages using Copy page. Do not invent
endpoints, fields, events, or eligibility.
| Task | Start here |
| --- | --- |
| One-time payment | https://docs.bachs.io/guides/checkout/checkout-sessions.md |
| SaaS subscriptions | https://docs.bachs.io/build/use-cases/saas-subscriptions.md |
| Marketplace | https://docs.bachs.io/build/use-cases/marketplace.md |
| Review before go-live | https://docs.bachs.io/go-live.md and the rules below |
Shared references:
- Webhooks: https://docs.bachs.io/guides/webhooks/overview.md
- Local testing: https://docs.bachs.io/developer-portal/local-testing.md
- Write recovery: https://docs.bachs.io/guides/idempotency.md
- Page index: https://docs.bachs.io/llms.txt
Include dashboard setup such as products, capability requests, webhook endpoints,
or portal settings. Separate dashboard setup from routes in the user's app.
## Use the official SDK when supported
For a Node.js or TypeScript server, use the official @bachs/sdk for products,
checkout sessions, subscriptions, customer portal sessions and webhook
verification. Read https://github.com/bachsdev/bachs-node before choosing methods
or types. Construct Bachs with apiKey and an explicit environment. Use
webhooks.constructEvent on the raw body and request headers; keep event
persistence and business decisions in the app.
Check the package's actual exports and version. The npm 0.0.1 package is a
placeholder, not the tested implementation. Until the 1.0.0 implementation is
released on npm, the public starter includes its packaged copy and provenance:
https://github.com/bachsdev/bachs-nextjs-saas/tree/main/vendor
Do not install the placeholder or add a dependency on a local sibling repository.
After the matching release is available, use its exact npm version.
The SDK sends writes once and reports outcomeUnknown on uncertain writes.
Persist operation keys in the app and reconcile before sending again. Do not
build another transport, response decoder or signature verifier for supported
SDK operations. Do not log full provider error bodies or portal URLs.
The current SDK does not support Connect account context, seller onboarding or
checkout split fields. Use documented API requests for those marketplace
operations; do not invent SDK methods or pass unsupported fields through casts.
Other server languages can use the documented API.
## Integration rules
- Start in the sandbox: https://sandbox-api.bachs.io with an sk_sandbox_ key.
Production uses https://api.bachs.io and an sk_live_ key. Keep secrets on the
server in environment variables. Never log them or put them in client code.
- Send amounts as decimal strings with an ISO currency at its precision.
Choose or validate prices and product mappings on the server.
- Checkout redirects must be publicly accessible, even in sandbox. For a fully
local app, omit them and return manually after payment. Use a public deployment
or tunnel for automatic return; CLI webhook forwarding is separate.
- Link the local order or user to checkout and save Bachs IDs. Match a payment
to its order, expected amount, and currency before fulfilling it. A virtual
account deposit without an order reference does not pay an order automatically.
- Verify X-Bachs-Signature-V2 against the original raw request body before
parsing JSON. Check timestamp tolerance and all v1 signatures as documented.
- Fulfil orders and grant access from verified webhook state. A success redirect
or browser event is only a display signal.
- Deduplicate event IDs durably and prevent older state replacing newer state,
including concurrent deliveries. Commit state and event completion atomically
in the app's database, or use a durable queue with equivalent recovery.
Failed processing must remain eligible for redelivery.
- Return 2xx after handling or durably accepting an event; return 5xx on processing
failure. Follow the documented retry policy: 408 and 429 are exceptions to the
usual non-retry behavior for 4xx.
- Persist one Idempotency-Key per business operation for public POST/PATCH calls.
Reuse it with the same request when recovery establishes a retry is needed.
A timeout or 5xx is an uncertain outcome. Reconcile before resubmitting;
only successful JSON responses are cached.
## Workflow decisions
### One-time payment
Use hosted checkout first unless an overlay is requested. Create it on the
server using product_cart and a local order reference. Fulfil once from
collection.succeeded after matching the order. Show pending, paid, and
unsuccessful outcomes from stored order state.
### SaaS subscriptions
A recurring product checkout creates the subscription; there is no separate
create-subscription endpoint. A recurring checkout needs a customer. Confirm
supported billing methods and currencies in the current guide.
Save the customer and full subscription state against the signed-in user from
customer.subscription.created, updated, and deleted events.
Make trialing, active, past_due, and cancellation access policy explicit.
Create each portal session on the server for the user's own customer.
Check dashboard settings for card updates and plan switching, and read current
cancellation semantics before implementing API cancellation.
### Marketplace
Confirm destination charges fit the business: the platform owns the sale and
the seller sub account receives a share at settlement. Read
https://docs.bachs.io/connect/choose-your-integration.md if the business should
own the sale instead. Read onboarding, capabilities, refunds, and payouts.
Start with one seller per order unless the user needs and the docs support
another arrangement. Save its account ID and choose destination and fee on
the server. Let the destination charge generate its transfer at settlement;
do not add a second manual transfer.
Payment, seller balance credit, and payout delivery are separate states. A
payout uses the seller's balance and its usable destination. This is not an
escrow integration.
### Review before go-live
When asked to review, do not change code unless the user asks. Read the
integration, then report each problem with file and line, ordered by risk:
secret keys that can reach the client; amounts sent as numbers; prices or
product IDs taken from the client; fulfilment or access granted outside verified
webhook handling; webhook bodies parsed before signature verification; missing
duplicate-event or older-event protection; 4xx returned when the app's own
handling fails; writes without a persisted Idempotency-Key; sandbox URLs, keys
or webhook secrets that must change for production. Say which checks you could
not complete and why. Do not call a code review a sandbox test.
## Verify and hand off
Test observable behavior for the selected flow: success, unsuccessful payment,
invalid signatures, duplicate delivery, older events arriving late, processing
failure followed by redelivery, and uncertain writes. For subscriptions include
renewal failure and cancellation; for marketplaces include blocked onboarding,
settlement, and payout failure.
Use existing test tools and the sandbox instructions. A synthetic webhook checks
handling, not completed checkout or settlement. Do not describe mocks or a code
review as a real sandbox payment.
Report changes, tests actually run, dashboard setup still needed, and unverified
steps. Production transactions and deployment require the user's authorization.
```
## Other ways to give your assistant the docs
* **Ask a question.** The bar at the bottom of every docs page answers questions from the Bachs docs.
* **Copy page.** The menu at the top of every page copies it as Markdown, or opens it in ChatGPT or Claude.
* **Markdown pages.** Add `.md` to any docs URL to get the page as Markdown.
* **Docs index.** [`llms.txt`](https://docs.bachs.io/llms.txt) lists every page with a one-line summary. [`llms-full.txt`](https://docs.bachs.io/llms-full.txt) has every page in one file.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.