> ## 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.

# Prompts

> Three tested prompts that get a coding assistant to build Bachs one-time payments or subscriptions in your app, or review your integration before go-live. Nothing to install.

Three prompts, each for one complete job. Copy a prompt into a coding assistant that can work with your app's code, such as Claude Code, Cursor, GitHub Copilot or Codex. Each prompt tells the assistant what to read, what to build, which rules to follow, and what to test. Then use the checks under each prompt to confirm the result yourself.

**Nothing to install.** If you use Bachs on many tasks, the [Bachs skill](/build/ai/skills) gives your assistant the same guidance automatically.

Starting a new app? [Choose a starter template](/build/starters/overview) first, then use a prompt to adapt it.

## Before you start

* Have an app your assistant can inspect, and decide what customers will buy.
* Get a [sandbox API key](/authentication). Keep it in your server's environment; do not paste it into a chat.
* Let your assistant read the linked docs. If it cannot open them, use **Copy page** on each guide and paste the content alongside the prompt.
* Use the [Bachs CLI](/cli/overview) to [forward sandbox webhooks to your machine](/developer-portal/local-testing).

Checkout return URLs must be public. For a fully local app, omit checkout redirects and return to the app manually after paying; the CLI still forwards webhooks locally. Use a public deployment or tunnel if you need an automatic return.

Every prompt includes its own integration rules. You can use it without creating an `AGENTS.md` file or installing a skill.

## Build with the SDK

For a Node.js or TypeScript server, use the [official Bachs SDK](https://github.com/bachsdev/bachs-node). It handles API requests, typed responses, and webhook signature verification. Your app still owns authentication, order state, access, and delivery recovery.

The [Next.js SaaS starter](https://github.com/bachsdev/bachs-nextjs-saas) uses the SDK and includes its tested package while the npm release is being prepared. The current npm 0.0.1 package is a placeholder. Follow the starter's package instructions instead of installing that version.

Connect onboarding, account context, and marketplace splits currently use the documented API because these operations are not yet supported by the SDK.

## Choose a prompt

| You want to | Use |
| - | - |
| Sell an item, booking or digital product once | [Accept a one-time payment](#accept-a-one-time-payment) |
| Charge for ongoing access to your product | [Sell subscriptions](#sell-subscriptions) |
| Check an integration before real customers pay | [Review before go-live](#review-before-go-live) |

Building a marketplace? Its prompt is on the [marketplace use case](/build/use-cases/marketplace#build-it-with-an-ai-assistant), because Connect is not yet in the SDK.

## Accept a one-time payment

**What you'll build:** a customer chooses an item, pays on Bachs checkout, and your app fulfils the order after confirming payment.

**Have ready:** what you sell, its price and currency, and the action that completes an order. Products can be created in the dashboard or through the [Products API](/guides/products/overview).

```text Prompt theme={"dark"}
Add Bachs one-time payments to this app. Inspect its framework, authentication,
order records, and payment code first. Reuse those conventions. Ask for the
item, currency, or fulfilment decision if missing.

For a Node.js or TypeScript server, use the official SDK for checkout and
webhooks.constructEvent for signature verification. Read its supported methods
and release instructions at https://github.com/bachsdev/bachs-node and
https://github.com/bachsdev/bachs-nextjs-saas/tree/main/vendor.
Check the installed version; npm 0.0.1 is only a placeholder. Do not reimplement
the SDK transport. For another server language, use the documented API.

Read:
https://docs.bachs.io/guides/checkout/checkout-sessions.md
https://docs.bachs.io/guides/webhooks/overview.md
https://docs.bachs.io/build/use-cases/digital-products.md
https://docs.bachs.io/guides/webhooks/events/collection-succeeded.md
https://docs.bachs.io/guides/idempotency.md

Use https://sandbox-api.bachs.io with BACHS_API_KEY on the server. Explain
dashboard setup, including products and webhook events.

Create checkout on the server with product_cart and our order reference.
Choose prices and product IDs on the server. Save the checkout ID and expected
amount and currency with the order, then redirect to checkout_url. For local testing, omit checkout return URLs; if configured, they must be public.

Verify X-Bachs-Signature-V2 on the raw body before parsing JSON, including
timestamp tolerance and every v1 signature. Fulfil once on checkout.completed
or collection.succeeded, whichever arrives first, after retrieving the checkout
and matching it to the order, amount, and currency. Store event IDs durably; make
fulfilment and event completion atomic or recoverable. Return 5xx on handling
failure. The success page reads our order state and handles a delayed webhook;
visiting it never marks an order paid.

Keep secrets server-side and amounts as decimal strings. Persist an
Idempotency-Key for each write operation. Reconcile an uncertain write before
retrying with the same key and unchanged request.

Test success, unsuccessful checkout, a bad signature, duplicate delivery, and
failed processing followed by redelivery. Report what you actually ran, what
I must configure, and how to complete a real sandbox checkout. Read linked
docs for missing details; do not invent API behavior.
```

### Check the result

* A successful sandbox checkout pays the correct order and fulfils it once.
* Opening the success URL before paying leaves the order unpaid.
* An unsuccessful checkout does not fulfil the order.
* Redelivery cannot repeat fulfilment; failed handling can recover on redelivery.
* An unrelated payment or virtual-account deposit cannot pay the order.

After this works, add an [overlay checkout](/guides/checkout/overlay-checkout), [local pricing](/guides/products/local-pricing), or [refunds](/guides/refunds).

## Sell subscriptions

**What you'll build:** monthly and yearly plans, access that follows subscription state, and a **Manage billing** button for the customer portal.

**Have ready:** signed-in users, your plans, and a decision about access during a failed renewal. The current [subscription guide](/guides/subscriptions/overview) supports USD card billing; [free trials](/guides/subscriptions/trials) are in beta.

```text Prompt theme={"dark"}
Add Bachs subscriptions to this app. Inspect its authentication, database,
access checks, and billing code first. Reuse them. Ask for missing plan details
or the access policy during payment recovery.

For a Node.js or TypeScript server, use the official SDK for products,
checkout, customer portal sessions, and webhooks.constructEvent. Read
https://github.com/bachsdev/bachs-node and the package instructions at
https://github.com/bachsdev/bachs-nextjs-saas/tree/main/vendor.
Check the installed version; npm 0.0.1 is only a placeholder. Keep persistent
keys and business state in our app; handle SDK outcomeUnknown by reconciling.
For another server language, use the documented API.

Read:
https://docs.bachs.io/build/use-cases/saas-subscriptions.md
https://docs.bachs.io/guides/webhooks/overview.md
https://docs.bachs.io/guides/idempotency.md

Use https://sandbox-api.bachs.io and server-side BACHS_API_KEY. Omit checkout return URLs for local testing; configured redirects must be public. Explain how
to create recurring products in the dashboard or API, configure portal settings,
and forward the five webhook events named in the use case.

Map a plan key to a product ID on the server. Create checkout with product_cart,
customer, billing_currency, and metadata.user_id. Recurring checkout starts the
subscription; there is no create-subscription endpoint. If the user already
has access, direct them to manage billing.

Verify X-Bachs-Signature-V2 on the raw body, with timestamp tolerance and all
v1 signatures. From customer.subscription.created, updated, and deleted, save
the customer ID and full subscription state against our user. Deduplicate
durably and prevent older events overwriting newer state, including concurrent
deliveries. Commit state and event completion together; return 5xx on failure.

Decide access from stored state, including trialing, active, past_due, and
cancellation. The success page only reads that state. Create each portal
session on the server for the signed-in user's own customer ID. Check the
documented portal settings and cancellation defaults.

Keep secrets server-side and amounts as decimal strings. Persist one
Idempotency-Key per write operation; reconcile uncertain writes before retrying.

Test activation, duplicate and out-of-order events, failed handling followed by
redelivery, renewal failure, and cancellation at period end. Report tests
actually run, remaining setup, and real sandbox checkout steps. Read linked
docs for missing details; do not invent behavior.
```

### Check the result

* A sandbox payment saves the user's customer ID and subscription, then grants access.
* A redirect alone cannot grant access.
* Duplicate or older events cannot undo a later cancellation.
* **Manage billing** opens the signed-in user's own customer portal.
* Scheduled cancellation keeps access for the remaining paid period; immediate cancellation removes it.
* Renewal failure follows your access policy and can recover after a successful retry.

The [full walkthrough](/build/use-cases/saas-subscriptions) includes requests, webhook examples, and a go-live checklist. Add [trials](/guides/subscriptions/trials) or [plan changes](/guides/subscriptions/manage) after the basic flow works.

## Review before go-live

**What you get:** a list of problems in your Bachs integration, by file and line and ordered by risk, with what correct code does. The assistant does not change your code.

**Have ready:** an integration you have built, with or without an assistant. Run this before you switch to production keys, and again after large changes.

```text Prompt theme={"dark"}
Review this codebase's Bachs payment integration before we go live. Do not
change any code.

First read:
https://docs.bachs.io/go-live.md
https://docs.bachs.io/guides/webhooks/overview.md
https://docs.bachs.io/guides/checkout/checkout-sessions.md
https://docs.bachs.io/guides/idempotency.md

Then read our integration: checkout, webhook handling, success or return pages,
billing or portal routes, and configuration.

Report each problem with its file and line, ordered by risk, with one sentence
on why it matters and what correct code does. Check at least:
- secret keys or webhook secrets that could reach the browser, logs or the
  repository
- prices, amounts or product IDs taken from the client
- amounts sent as numbers instead of decimal strings with a currency
- orders fulfilled or access granted anywhere other than verified webhook
  handling
- a payment fulfilled without matching it to our order, amount and currency
- webhook bodies parsed before the signature is checked, a missing timestamp
  check, or only the first v1 signature checked
- missing protection against duplicate or out-of-order webhook events
- 4xx responses returned when our own handling fails (Bachs does not retry
  them)
- POST or PATCH requests without a persisted Idempotency-Key
- requests the Bachs docs say are invalid
- sandbox URLs, keys or secrets that must change for production

Then list anything you could not check and why. Do not describe this review as
a sandbox test.
```

### Check the result

* Every problem names a file and line you can open.
* Fix the problems, then run the prompt again until it reports none you disagree with.
* A review reads code. It does not prove a payment works. Complete a real sandbox payment, including a failure case, before you go live. See [Test payment outcomes](/integrate/sandbox#test-payment-outcomes).

Then follow [Go live](/go-live), or [Take Connect live](/connect/go-live) for a marketplace: create production resources, use the production key and API URL, and register a webhook endpoint with its own signing secret.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.