> ## Documentation Index
> Fetch the complete documentation index at: https://docs.piriod.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration flows

> End-to-end scenarios for the most common Piriod use cases.

This page describes the most common flows. Each step links to the relevant API
Reference entry.

## 1. One-shot billing: customer → invoice → payment

<Steps>
  <Step title="Create a customer">
    POST `/customers/` with `name`, `address`, `country`, `state` and (when applicable)
    `tax_id` + `tax_settings`. The response includes a customer `id` you will reuse below.
  </Step>

  <Step title="Issue an invoice">
    POST `/invoices/` with the `customer` id and the line items. The invoice starts
    in `draft` status.
  </Step>

  <Step title="Finalize the invoice">
    Call the `finalize` action on the invoice to send it to the tax agency
    (when applicable) and lock its content.
  </Step>

  <Step title="Charge the customer">
    POST `/payments/` linking the invoice and a reusable `source`, or share a
    payment link from `/payment_links/links/` for hosted checkout.
  </Step>
</Steps>

## 2. Recurring billing with subscriptions

<Steps>
  <Step title="Define your catalog">
    Create products at `/products/`, plans at `/plans/` and optional add-ons or
    coupons.
  </Step>

  <Step title="Subscribe a customer">
    POST `/subscriptions/` with the customer, the plan and the chosen frequency.
    Piriod will compute the next billing date.
  </Step>

  <Step title="Generate invoices automatically">
    Each cycle Piriod generates the invoice; the matching webhook event lets you
    react. You can also call the `process` action manually.
  </Step>

  <Step title="Pause, resume or cancel">
    Use `pause`, `resume` and `DELETE` on the subscription resource.
  </Step>
</Steps>

## 3. Hosted payment links

<Steps>
  <Step title="Create a link">
    POST `/payment_links/links/` with the amount and currency. Capture the
    `publishable_key` from the response.
  </Step>

  <Step title="Share the hosted page">
    Send `/publishable/payment_links/links/{key}/hosted/` to the payer. They
    complete the checkout in Piriod-hosted UI.
  </Step>

  <Step title="Track the result">
    The created `intent` exposes status transitions (authorized → captured →
    finalized) you can poll or listen for via webhook.
  </Step>
</Steps>

## 4. Procurement: receive supplier documents

<Steps>
  <Step title="Register a supplier">
    POST `/suppliers/` with their tax identifier and contact info.
  </Step>

  <Step title="Record a purchase">
    POST `/purchases/` (or `/purchases/credit-notes/` for credit notes) with the
    supplier and line items.
  </Step>

  <Step title="Issue retentions">
    POST `/retentions/` linked to the purchase when withholding taxes apply.
  </Step>

  <Step title="Finalize and report">
    Call `finalize` on each document to submit it to the tax agency.
  </Step>
</Steps>