# Billing Subscription Integration Knowledge Index

## How to use this guide

Enter this page after [Product Decision](https://cdn.marmot-cloud.com/page/antom-integration-doc/references/product-decision.md) identifies Billing subscriptions; do not repeat product selection. This page organizes the integration plan and reading scope. It is not a required entry point for every Billing capability.

Once Billing subscriptions are selected, backend subscription creation, card payments, or Antom-hosted card collection affect the integration path and payment samples on this page. Continue with the selected language and path under `billing/sample-code/`.

1. **Determine the task scope.** For a complete initial subscription integration, deliver the plan in section 4 before coding. Existing Product, Price, Customer, or Meter resources reduce creation steps but do not remove this plan requirement. For an added capability, a single API, or a field question in an existing integration, go directly to the relevant knowledge and fill only the affected context. For diagnosis, use [Troubleshooting](https://cdn.marmot-cloud.com/page/antom-integration-doc/troubleshoot/troubleshooting-guide.md).
2. **Outline the plan before reading business documentation.** Extract pricing, the integration experience, collection method, existing resources, and required capabilities from the user's description and project. Ask only about missing information that changes resource dependencies, calls, or result handling; do not ask about every item in turn.
3. **Select the reading scope first.** For a complete integration, select applicable initial integration knowledge, required capabilities, and resources that actually need preparation. Skip unmatched rows, do not reload material already read, and do not traverse indexes when the operation can be located directly.
4. **Read each applicable item and incorporate it into one plan.** When the user requires renewal, trials, or other capabilities, read their rules while forming the plan. Incorporate their effects on resources, creation, initial results, and later cycles into that plan instead of starting another complete integration flow.
5. **Stop when the task is covered.** Once configuration, call order, data relationships, and result handling are clear, stop expanding business reading. During coding, add only the necessary SDK, sample, API reference, and verification material.

Include only capabilities explicitly requested or required for the integration. Unmentioned capabilities are neither enabled by default nor treated as explicitly excluded.

## 1. Organize the integration plan

Use the table below to record confirmed requirements and unresolved items. Then select the corresponding documents in sections 2 and 3 to verify support and the integration approach.

Recording unresolved items does not mean asking about each one. Ask only for information that changes product selection, supported behavior, or the implementation path and cannot be determined from context. In consultations and plans, an unresolved item blocks only conclusions that depend on it. Continue reading and explaining the confirmed parts, and state remaining conditions and their impact. For example, when the payment method and market are unknown, still explain established resource preparation, subscription rules, and invoice requirements, without promising a specific payment method or card-binding flow. Customer IDs, credentials, and specific business parameters may be runtime inputs to generic methods; verify their actual values before executing operations.

| Plan element | What to determine | Effect on reading scope |
| --- | --- | --- |
| Task scope | Complete subscription service / initial integration only / a limited task in an existing integration | A complete service includes renewal and payment recovery. Limited tasks need not repeat the core integration. |
| Pricing | Fixed / per-seat / metered / tiered / package / mixed; multiple models may apply | Determine the pricing model, quantity source, and resource dependencies. Distinguish ordered quantities from reported usage to decide whether a Meter is needed. |
| Integration experience | Checkout creates a subscription through a Payment Session / backend creates a Subscription and calls Pay when needed | Select CKP or Direct API respectively. Hosted card collection alone does not imply CKP. |
| Collection method | Automatic charging / customer-initiated invoice payment / confirmation after offline collection | Determine this separately from the technical path and verify support in the documentation. Creating an Invoice does not itself select invoice-based collection. |
| Resource preparation | For each resource: reuse / Dashboard creation / API creation | Mixed preparation is allowed. Read preparation details only for missing resources. Direct API does not require creating every resource through APIs. |
| Other requirements | Requested or required trials, discounts, renewals, changes, tax, etc. | Select the corresponding knowledge in section 3 and incorporate its effects when forming the plan. |

**Reading scope example:** For "fixed monthly pricing, Price already created in Dashboard, Customer created by API, CKP, with renewals," select Customer preparation and price reuse, initial CKP integration, initial result handling, and renewal/recovery. Add pricing and resource relationships if the configuration or relationships are unclear. Do not expand into Product/Price creation tutorials, Meter, trials, discounts, or Direct API. Add the selected language samples during coding preparation.

## 2. Initial integration and resource preparation

A complete integration must establish pricing and resource relationships, resource preparation, the integration path, and result handling. Select documents for current knowledge gaps, rather than reading every row in order. Do not reload documented answers already available in context. Limited tasks need only the affected knowledge, but must still read relevant samples in the selected language before coding.

| Knowledge area | When to read | Entry and scope | Questions to resolve |
| --- | --- | --- | --- |
| Pricing and resource relationships | Pricing configuration, quantity source, or resource relationships are not yet clear | [Subscription pricing and resource relationships](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/subscription-integration/pricing-and-resources.md) | Price items, quantity sources, Meter dependencies, objects, and ID relationships. Verify billing timing and support for complex combinations. |
| Resource preparation | Resources must be created, or existing resources checked against the plan | [Subscription resource preparation](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/subscription-integration/resource-preparation.md) | Reuse, Dashboard/API preparation, customer collection, configuration, prerequisites, and obtaining IDs. Address only resources missing for this task. |
| Integration path | Initial subscription creation, payment, or authorization must be implemented or changed | Select only [Initial CKP integration](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/subscription-integration/checkout-page.md) or [Initial Direct API integration](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/subscription-integration/direct-api.md) | Calls using prepared resources, parameter handoff, client actions, and data storage. Do not mix paths. |
| Result handling | Subscription activation, payment confirmation, notification configuration, or recovery must be implemented or completed; required for a complete initial implementation | [Initial result handling](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/subscription-integration/initial-results.md) | Notification selection, exact fields and states, business actions, endpoint configuration, signature verification, idempotency, out-of-order events, and query-based recovery. Path guides do not duplicate the result matrix. |

Verify API semantics that affect resource dependencies, call order, payment method preparation, or completion criteria while forming the plan; do not defer all of these questions until coding. Add full field constraints, SDK types, and implementation samples as needed during coding. For trials, zero-value initial invoices, and fully metered subscriptions, separately establish whether payment is currently required, how to prepare the payment method for later charges, and which operation results prove readiness.

These documents explain their respective topics directly, without another scenario index. For complete fields, Dashboard operations, or payment method details, follow the targeted reference or guide at the relevant point. Select language samples through section 5.

**Required dependencies and boundaries:**

- Pricing determines price items, quantity sources, and Meter dependencies. Prepare a Product before creating a Price; a metered Price also requires its associated Meter. Read Meter reporting and error handling through section 3.
- Resources may use different preparation methods. Customer preparation or collection also depends on the integration path and its support conditions. Use the path comparison in the resource preparation guide to verify fields and constraints; do not assume every resource supports Dashboard creation or automatic checkout creation.
- Continue design once preparation methods are established. Before actually creating a subscription, the required resources and IDs must be available. Reference resources already prepared in Dashboard without recreating them.
- Read applicable section 3 capabilities while forming the plan and incorporate them into that same plan. Verify support for invoice payment or offline confirmation before applying any collection steps; do not simply reuse automatic charging steps.
- A successful creation response or browser return does not establish the final business result. Handle trials and zero-value invoices according to their own rules, without requiring an actual payment where none is due.

## 3. Add required capabilities to the same plan

These entries are not separate flows. After reading, identify the affected parts of the core integration, configuration, calls, notifications, and business actions. Keep the baseline rules where nothing changes.

| Requirement | Preferred document and reading scope | Implementation decisions |
| --- | --- | --- |
| Usage collection and reporting | Reporting and error handling in [Meter](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/capabilities/meter.md) | Usage events, Customer association, reporting, and error recovery. Read the query boundaries when reconciling usage. Connect cycle settlement to invoice handling; do not reload Meter creation already covered in section 2. |
| Discounts and promotion codes | [Coupon and promotion code management](https://docs.antom.com/ac/billing/coupon_and_promotion_management.md) | Resource preparation, application point, discount value, validity, and restrictions. If "one-time use" is ambiguous, clarify once globally versus once per customer instead of choosing a default. Do not ask again if explicit. Handle redemption scope separately from discount duration. |
| Free or paid trials, or changes to an existing trial | [Subscription trials](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/subscription-integration/trial.md); respect its support boundaries for paid trials | Creation or trial adjustment, evidence for activation, duration, payment method readiness, and trial-end handling. |
| Pricing over successive periods | [Pricing over successive periods](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/subscription-integration/phased-pricing.md); read when users describe different charges over time | Distinguish free trials, temporary discounts, and subscription price changes. Establish duration, effective time, and invoice results; do not assume automatic multi-phase scheduling is supported. |
| Automatic renewal and payment recovery | Automatic renewal and dunning sections of [Subscription lifecycle](https://docs.antom.com/ac/billing/subscription_lifecycle.md), for `CHARGE_AUTOMATICALLY` | Required for a complete subscription service. Establish saved payment method readiness through the selected integration path, then incorporate recurring invoices and recovery into the same plan. Merchant access during arrears is a project policy; it cannot prevent Antom termination. Updating a payment method does not itself settle an outstanding invoice. |
| Subscription changes, pause/resume, and cancellation | For price or quantity changes, read the relevant operation in [Subscription updates](https://docs.antom.com/ac/billing/subscription_update.md). For pause, resume, cancellation, or revoking a scheduled cancellation, read [Cancellation and pause/resume](https://docs.antom.com/ac/billing/subscription_cancellation.md). Use the corresponding API field definitions for request parameters rather than copying guide examples. | Establish applicable states, effective timing, invoice or credit note effects, and completion evidence. Read only the requested operation; cancellation timing does not define price-change timing. |
| Customer-initiated invoice payment / offline confirmation | Relevant sections of [Invoice and payment management](https://docs.antom.com/ac/billing/invoice_payment_management.md) | First verify support for the subscription and selected pricing model, then establish collection steps and result evidence. |
| Prepaid credit application | [Credit Grant](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/capabilities/credit-grant.md) | Credit sources, grants, application, and their relationship to payment. Purchasing a token package does not automatically imply this capability. |
| Customer self-service portal | [Customer Portal](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/capabilities/customer-portal.md) | Entry point, permissions, and allowed operations. |
| Emailed invoices, receipts, adjustments, or refunds | Relevant operations in [Invoice and payment management](https://docs.antom.com/ac/billing/invoice_payment_management.md) | Required calls and results, without expanding into unrelated invoice capabilities. |
| Tax | [Documented tax capabilities](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/subscription-integration/tax.md) | Tax settings, jurisdiction registration, calculation and queries, and the boundaries of their connection to subscription invoices. |

**Combined behavior requires evidence.** For example, metered billing plus trials and renewals requires confirmation of how trial usage is billed, when chargeable invoices are generated, and when service is activated or extended. Support for each feature separately does not establish support for the combination. Do not derive business rules by joining samples. Where evidence is insufficient, explain the impact and unresolved items, and complete unaffected work.

## 4. Deliver an integration plan

When the user explicitly requests a plan, or the task implements a complete subscription integration, verify the relevant knowledge and deliver the plan as a Markdown file. For a complete integration, deliver the plan before coding from it. When a change to an existing integration affects the integration method, billing rules, resource dependencies, or result handling, update its existing plan; if none exists, document only the affected change. Consultation, single API operations, simple CRUD, and local fixes do not require a plan file unless the user requests one.

Update the existing file when a plan is available. Follow project conventions or user instructions for the filename and location; otherwise choose an appropriate location without a separate clarification. Use the template below as needed, without requiring every cell to be filled or adding approval or progress tracking.

| Plan section | Content |
| --- | --- |
| Goals and scope | Business goals, this delivery, and explicit exclusions. |
| Subscription rules | Confirmed pricing, cycles, trials, discounts, and renewals. |
| Integration approach | Selected path, collection method, and rationale. |
| Resource preparation | Dependencies, reuse/Dashboard/API method, required configuration, and readiness for each resource. |
| Implementation flow | Call order and data relationships for preparation, creation, payment or authorization, and subsequent actions. |
| Result handling | Notifications, fields, states, actions, idempotency, and recovery from unknown outcomes. |
| Implementation and verification | Technology stack, required configuration, verification scenarios, and completion criteria. |
| Open questions and sources | Missing information and its impact; links to the guides, API references, and samples used. |

Update the plan when key decisions change. Do not present unresolved items as conclusions or planned work as completed. Record configuration locations for secrets, never the secrets themselves. Subsequent Agents continue from confirmed decisions and verify and update them if the environment or API contracts change.

## 5. Coding and verification

1. Confirm the language and platform, and read [SDK selection](https://cdn.marmot-cloud.com/page/antom-integration-doc/references/select-sdk.md).
2. Select one language from the [Billing sample index](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/sample-code/index.md), read SDK Basics, then select resource preparation, pricing, CKP/Direct API, result handling, and capability samples according to the plan. For existing resources, reference IDs without reading creation samples. **Read relevant samples before simple CRUD too; there is no bypass for these operations.** Direct API subscriptions also require the payment sample matching the selected method: wallets and similar methods, Antom-hosted card collection, or merchant-collected card data. Read only the selected approach and do not mix request fields or continuation steps across approaches.
3. Samples demonstrate SDK usage; the plan determines functionality. A complete sample for every capability combination is unnecessary. If no exact sample exists, read the relevant shared samples, then implement against API contracts and confirmed SDK definitions. Do not infer methods from field names or claim to have read a shared sample that does not exist.
4. Read known API references directly; consult the [API index](https://cdn.marmot-cloud.com/page/antom-integration-doc/billing/api/index.md) only when the API is unknown. Read relevant [FAQ Coding](https://cdn.marmot-cloud.com/page/antom-integration-doc/troubleshoot/faq-coding.md) entries and follow the Skill's coding, security, and logging requirements.
5. Use [Billing self-check](https://cdn.marmot-cloud.com/page/antom-integration-doc/integration-guides/billing-self-check.md) and the Skill's general verification requirements to check the selected path, notification results, and capability combinations. Do not recreate Dashboard-prepared resources in code. State honestly what was not actually verified.
