1. One-shot billing: customer → invoice → payment
1
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.2
Issue an invoice
POST
/invoices/ with the customer id and the line items. The invoice starts
in draft status.3
Finalize the invoice
Call the
finalize action on the invoice to send it to the tax agency
(when applicable) and lock its content.4
Charge the customer
POST
/payments/ linking the invoice and a reusable source, or share a
payment link from /payment_links/links/ for hosted checkout.2. Recurring billing with subscriptions
1
Define your catalog
Create products at
/products/, plans at /plans/ and optional add-ons or
coupons.2
Subscribe a customer
POST
/subscriptions/ with the customer, the plan and the chosen frequency.
Piriod will compute the next billing date.3
Generate invoices automatically
Each cycle Piriod generates the invoice; the matching webhook event lets you
react. You can also call the
process action manually.4
Pause, resume or cancel
Use
pause, resume and DELETE on the subscription resource.3. Hosted payment links
1
Create a link
POST
/payment_links/links/ with the amount and currency. Capture the
publishable_key from the response.2
Share the hosted page
Send
/publishable/payment_links/links/{key}/hosted/ to the payer. They
complete the checkout in Piriod-hosted UI.3
Track the result
The created
intent exposes status transitions (authorized → captured →
finalized) you can poll or listen for via webhook.4. Procurement: receive supplier documents
1
Register a supplier
POST
/suppliers/ with their tax identifier and contact info.2
Record a purchase
POST
/purchases/ (or /purchases/credit-notes/ for credit notes) with the
supplier and line items.3
Issue retentions
POST
/retentions/ linked to the purchase when withholding taxes apply.4
Finalize and report
Call
finalize on each document to submit it to the tax agency.