openapi: 3.0.3
info:
title: Octobat API
description: >-
Octobat is a billing, invoicing, and tax-compliance platform for online
businesses. This OpenAPI document describes the public REST API at base URL
https://apiv2.octobat.com. The API is Stripe-style: resource-oriented, form
or JSON request bodies, and HTTP Basic authentication using your secret key
as the username with an empty password (curl: -u sk_live_xxx:). Test-mode
keys (sk_test_) and live-mode keys (sk_live_) select the environment.
Endpoint provenance: paths marked "confirmed" are demonstrated directly in
Octobat's own documentation (register-transactions and tax-calculation
guides). The remaining CRUD and action paths are modeled from Octobat's
official Ruby SDK (github.com/0ctobat/octobat-ruby), which derives resource
URLs as the snake_cased, pluralized class name and uses POST to create,
PATCH to update, GET to retrieve/list, and DELETE to remove. Request and
response schemas are representative, not exhaustive; consult the live API
reference at https://v2apidoc.octobat.com for full field-level detail.
Operating status: Octobat was acquired by Mirakl in November 2021. The
standalone marketing site now redirects to mirakl.com; docs.octobat.com and
apiv2.octobat.com remain available to existing integrators.
version: '2.0'
contact:
name: Octobat
url: https://docs.octobat.com
email: support@octobat.com
servers:
- url: https://apiv2.octobat.com
description: Octobat API v2 (production)
security:
- basicAuth: []
tags:
- name: Invoices
description: Compliant invoices, their items, and lifecycle actions.
- name: Credit Notes
description: Compliant credit notes issued against invoices.
- name: Transactions
description: Payments registered against invoices for reconciliation and tax reporting.
- name: Customers
description: Customers and their billing / tax details.
- name: Products
description: Products and their tax categorization.
- name: Tax Evidence
description: Real-time tax determination for customers and carts / checkouts.
- name: Coupons
description: Discount coupons for invoices and subscriptions.
- name: Subscriptions
description: Recurring-billing subscriptions and metered usage.
- name: Payouts
description: Settlement payouts and their balance transactions.
paths:
/invoices:
get:
operationId: listInvoices
tags: [Invoices]
summary: List invoices
description: >-
Lists invoices. Supports filtering by customer and by status, including
due / unpaid invoices, via query parameters.
parameters:
- name: customer
in: query
required: false
schema: { type: string }
description: Filter by customer ID.
- name: status
in: query
required: false
schema:
type: string
enum: [draft, confirmed, paid, due, uncollectible, cancelled]
description: Filter by invoice status (use "due" for unpaid invoices).
- name: limit
in: query
required: false
schema: { type: integer, default: 10 }
responses:
'200':
description: A list of invoices.
content:
application/json:
schema: { $ref: '#/components/schemas/InvoiceList' }
'401': { $ref: '#/components/responses/Unauthorized' }
post:
operationId: createInvoice
tags: [Invoices]
summary: Create an invoice
description: Creates a new invoice for a customer. (Confirmed in Octobat docs.)
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/InvoiceCreate' }
responses:
'200':
description: The created invoice.
content:
application/json:
schema: { $ref: '#/components/schemas/Invoice' }
'401': { $ref: '#/components/responses/Unauthorized' }
/invoices/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
operationId: retrieveInvoice
tags: [Invoices]
summary: Retrieve an invoice
responses:
'200':
description: The requested invoice.
content:
application/json:
schema: { $ref: '#/components/schemas/Invoice' }
'401': { $ref: '#/components/responses/Unauthorized' }
patch:
operationId: updateInvoice
tags: [Invoices]
summary: Update an invoice
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/InvoiceCreate' }
responses:
'200':
description: The updated invoice.
content:
application/json:
schema: { $ref: '#/components/schemas/Invoice' }
'401': { $ref: '#/components/responses/Unauthorized' }
delete:
operationId: deleteInvoice
tags: [Invoices]
summary: Delete an invoice
responses:
'200': { description: The invoice was deleted. }
'401': { $ref: '#/components/responses/Unauthorized' }
/invoices/{id}/items:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
post:
operationId: createInvoiceItem
tags: [Invoices]
summary: Add an item to an invoice
description: >-
Adds a line item to an invoice. Provide a tax_evidence ID (from the Tax
Evidence API) or explicit tax parameters. (Confirmed in Octobat docs.)
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/InvoiceItemCreate' }
responses:
'200':
description: The created invoice item.
content:
application/json:
schema: { $ref: '#/components/schemas/Item' }
'401': { $ref: '#/components/responses/Unauthorized' }
/invoices/{id}/confirm:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
patch:
operationId: confirmInvoice
tags: [Invoices]
summary: Confirm (finalize) an invoice
description: >-
Confirms an invoice, assigning it a sequential legal number and making
it immutable. (Confirmed in Octobat docs.)
responses:
'200':
description: The confirmed invoice.
content:
application/json:
schema: { $ref: '#/components/schemas/Invoice' }
'401': { $ref: '#/components/responses/Unauthorized' }
/invoices/{id}/send:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
post:
operationId: sendInvoice
tags: [Invoices]
summary: Send an invoice by email
responses:
'200':
description: The invoice, after sending.
content:
application/json:
schema: { $ref: '#/components/schemas/Invoice' }
'401': { $ref: '#/components/responses/Unauthorized' }
/invoices/{id}/set_payment_terms:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
patch:
operationId: setInvoicePaymentTerms
tags: [Invoices]
summary: Set payment terms on an invoice
responses:
'200':
description: The updated invoice.
content:
application/json:
schema: { $ref: '#/components/schemas/Invoice' }
'401': { $ref: '#/components/responses/Unauthorized' }
/invoices/{id}/mark_uncollectible:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
patch:
operationId: markInvoiceUncollectible
tags: [Invoices]
summary: Mark an invoice uncollectible
responses:
'200':
description: The updated invoice.
content:
application/json:
schema: { $ref: '#/components/schemas/Invoice' }
'401': { $ref: '#/components/responses/Unauthorized' }
/invoices/{id}/cancel:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
patch:
operationId: cancelInvoice
tags: [Invoices]
summary: Cancel an invoice
responses:
'200':
description: The cancelled invoice.
content:
application/json:
schema: { $ref: '#/components/schemas/Invoice' }
'401': { $ref: '#/components/responses/Unauthorized' }
/invoices/{id}/cancel_and_replace:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
patch:
operationId: cancelAndReplaceInvoice
tags: [Invoices]
summary: Cancel and replace an invoice
responses:
'200':
description: The replacement invoice.
content:
application/json:
schema: { $ref: '#/components/schemas/Invoice' }
'401': { $ref: '#/components/responses/Unauthorized' }
/invoices/pdf_export:
post:
operationId: exportInvoicesPdf
tags: [Invoices]
summary: Export invoices to PDF
responses:
'200': { description: Export accepted. }
'401': { $ref: '#/components/responses/Unauthorized' }
/invoices/csv_export:
post:
operationId: exportInvoicesCsv
tags: [Invoices]
summary: Export invoices to CSV
responses:
'200': { description: Export accepted. }
'401': { $ref: '#/components/responses/Unauthorized' }
/credit_notes:
get:
operationId: listCreditNotes
tags: [Credit Notes]
summary: List credit notes
parameters:
- name: customer
in: query
required: false
schema: { type: string }
responses:
'200':
description: A list of credit notes.
content:
application/json:
schema: { $ref: '#/components/schemas/CreditNoteList' }
'401': { $ref: '#/components/responses/Unauthorized' }
post:
operationId: createCreditNote
tags: [Credit Notes]
summary: Create a credit note
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customer: { type: string }
invoice: { type: string }
currency: { type: string }
responses:
'200':
description: The created credit note.
content:
application/json:
schema: { $ref: '#/components/schemas/CreditNote' }
'401': { $ref: '#/components/responses/Unauthorized' }
/credit_notes/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
operationId: retrieveCreditNote
tags: [Credit Notes]
summary: Retrieve a credit note
responses:
'200':
description: The requested credit note.
content:
application/json:
schema: { $ref: '#/components/schemas/CreditNote' }
'401': { $ref: '#/components/responses/Unauthorized' }
/transactions:
get:
operationId: listTransactions
tags: [Transactions]
summary: List transactions
parameters:
- name: customer
in: query
required: false
schema: { type: string }
- name: invoice
in: query
required: false
schema: { type: string }
responses:
'200':
description: A list of transactions.
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionList' }
'401': { $ref: '#/components/responses/Unauthorized' }
post:
operationId: createTransaction
tags: [Transactions]
summary: Register a transaction
description: >-
Registers a successful payment so Octobat can reconcile it with an
invoice and drive tax reporting. (Confirmed in Octobat docs.)
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionCreate' }
responses:
'200':
description: The created transaction.
content:
application/json:
schema: { $ref: '#/components/schemas/Transaction' }
'401': { $ref: '#/components/responses/Unauthorized' }
/transactions/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
operationId: retrieveTransaction
tags: [Transactions]
summary: Retrieve a transaction
responses:
'200':
description: The requested transaction.
content:
application/json:
schema: { $ref: '#/components/schemas/Transaction' }
'401': { $ref: '#/components/responses/Unauthorized' }
patch:
operationId: updateTransaction
tags: [Transactions]
summary: Update a transaction
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/TransactionCreate' }
responses:
'200':
description: The updated transaction.
content:
application/json:
schema: { $ref: '#/components/schemas/Transaction' }
'401': { $ref: '#/components/responses/Unauthorized' }
/transactions/csv_export:
post:
operationId: exportTransactionsCsv
tags: [Transactions]
summary: Export transactions to CSV
responses:
'200': { description: Export accepted. }
'401': { $ref: '#/components/responses/Unauthorized' }
/customers:
get:
operationId: listCustomers
tags: [Customers]
summary: List customers
responses:
'200':
description: A list of customers.
content:
application/json:
schema: { $ref: '#/components/schemas/CustomerList' }
'401': { $ref: '#/components/responses/Unauthorized' }
post:
operationId: createCustomer
tags: [Customers]
summary: Create a customer
description: Creates a customer with billing and tax details. (Confirmed in Octobat docs.)
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CustomerCreate' }
responses:
'200':
description: The created customer.
content:
application/json:
schema: { $ref: '#/components/schemas/Customer' }
'401': { $ref: '#/components/responses/Unauthorized' }
/customers/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
operationId: retrieveCustomer
tags: [Customers]
summary: Retrieve a customer
responses:
'200':
description: The requested customer.
content:
application/json:
schema: { $ref: '#/components/schemas/Customer' }
'401': { $ref: '#/components/responses/Unauthorized' }
patch:
operationId: updateCustomer
tags: [Customers]
summary: Update a customer
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CustomerCreate' }
responses:
'200':
description: The updated customer.
content:
application/json:
schema: { $ref: '#/components/schemas/Customer' }
'401': { $ref: '#/components/responses/Unauthorized' }
delete:
operationId: deleteCustomer
tags: [Customers]
summary: Delete a customer
responses:
'200': { description: The customer was deleted. }
'401': { $ref: '#/components/responses/Unauthorized' }
/products:
get:
operationId: listProducts
tags: [Products]
summary: List products
responses:
'200':
description: A list of products.
content:
application/json:
schema: { $ref: '#/components/schemas/ProductList' }
'401': { $ref: '#/components/responses/Unauthorized' }
post:
operationId: createProduct
tags: [Products]
summary: Create a product
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ProductCreate' }
responses:
'200':
description: The created product.
content:
application/json:
schema: { $ref: '#/components/schemas/Product' }
'401': { $ref: '#/components/responses/Unauthorized' }
/products/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
operationId: retrieveProduct
tags: [Products]
summary: Retrieve a product
responses:
'200':
description: The requested product.
content:
application/json:
schema: { $ref: '#/components/schemas/Product' }
'401': { $ref: '#/components/responses/Unauthorized' }
patch:
operationId: updateProduct
tags: [Products]
summary: Update a product
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/ProductCreate' }
responses:
'200':
description: The updated product.
content:
application/json:
schema: { $ref: '#/components/schemas/Product' }
'401': { $ref: '#/components/responses/Unauthorized' }
/tax_evidences:
post:
operationId: createTaxEvidence
tags: [Tax Evidence]
summary: Create a tax evidence for a registered customer
description: >-
Determines the applicable tax for a registered customer and returns a
TaxEvidence with the applied rate and an ID to store with the order.
(Confirmed in Octobat docs.)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [customer]
properties:
customer: { type: string, description: Octobat customer ID. }
product_type: { type: string, description: Product type used for tax categorization. }
responses:
'200':
description: The created tax evidence.
content:
application/json:
schema: { $ref: '#/components/schemas/TaxEvidence' }
'401': { $ref: '#/components/responses/Unauthorized' }
/tax_evidence_requests:
post:
operationId: createTaxEvidenceRequest
tags: [Tax Evidence]
summary: Create a tax evidence request for a not-yet-registered buyer
description: >-
Calculates tax at cart / checkout time from a buyer's billing location,
with optional B2B reverse-charge via a tax number. (Confirmed in Octobat
docs.)
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [customer_billing_address_country]
properties:
customer_billing_address_country: { type: string }
customer_billing_address_zip: { type: string }
customer_billing_address_city: { type: string }
customer_tax_number: { type: string, description: For B2B reverse-charge validation. }
product_type: { type: string }
responses:
'200':
description: The created tax evidence request.
content:
application/json:
schema: { $ref: '#/components/schemas/TaxEvidence' }
'401': { $ref: '#/components/responses/Unauthorized' }
/tax_evidence_requests/for_supplier:
post:
operationId: createTaxEvidenceRequestForSupplier
tags: [Tax Evidence]
summary: Create a supplier-side tax evidence request
description: >-
Supplier-oriented tax determination (for platform / marketplace
self-billing and commission scenarios). Modeled from the Octobat Ruby
SDK for_supplier action.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
supplier: { type: string }
product_type: { type: string }
responses:
'200':
description: The created supplier tax evidence request.
content:
application/json:
schema: { $ref: '#/components/schemas/TaxEvidence' }
'401': { $ref: '#/components/responses/Unauthorized' }
/coupons:
get:
operationId: listCoupons
tags: [Coupons]
summary: List coupons
responses:
'200':
description: A list of coupons.
content:
application/json:
schema: { $ref: '#/components/schemas/CouponList' }
'401': { $ref: '#/components/responses/Unauthorized' }
post:
operationId: createCoupon
tags: [Coupons]
summary: Create a coupon
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CouponCreate' }
responses:
'200':
description: The created coupon.
content:
application/json:
schema: { $ref: '#/components/schemas/Coupon' }
'401': { $ref: '#/components/responses/Unauthorized' }
/coupons/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
operationId: retrieveCoupon
tags: [Coupons]
summary: Retrieve a coupon
responses:
'200':
description: The requested coupon.
content:
application/json:
schema: { $ref: '#/components/schemas/Coupon' }
'401': { $ref: '#/components/responses/Unauthorized' }
patch:
operationId: updateCoupon
tags: [Coupons]
summary: Update a coupon
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CouponCreate' }
responses:
'200':
description: The updated coupon.
content:
application/json:
schema: { $ref: '#/components/schemas/Coupon' }
'401': { $ref: '#/components/responses/Unauthorized' }
delete:
operationId: deleteCoupon
tags: [Coupons]
summary: Delete a coupon
responses:
'200': { description: The coupon was deleted. }
'401': { $ref: '#/components/responses/Unauthorized' }
/coupons/{id}/activate:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
patch:
operationId: activateCoupon
tags: [Coupons]
summary: Activate a coupon
responses:
'200':
description: The activated coupon.
content:
application/json:
schema: { $ref: '#/components/schemas/Coupon' }
'401': { $ref: '#/components/responses/Unauthorized' }
/coupons/{id}/unactivate:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
patch:
operationId: deactivateCoupon
tags: [Coupons]
summary: Deactivate a coupon
responses:
'200':
description: The deactivated coupon.
content:
application/json:
schema: { $ref: '#/components/schemas/Coupon' }
'401': { $ref: '#/components/responses/Unauthorized' }
/subscriptions:
get:
operationId: listSubscriptions
tags: [Subscriptions]
summary: List subscriptions
responses:
'200':
description: A list of subscriptions.
content:
application/json:
schema: { $ref: '#/components/schemas/SubscriptionList' }
'401': { $ref: '#/components/responses/Unauthorized' }
post:
operationId: createSubscription
tags: [Subscriptions]
summary: Create a subscription
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customer: { type: string }
currency: { type: string }
responses:
'200':
description: The created subscription.
content:
application/json:
schema: { $ref: '#/components/schemas/Subscription' }
'401': { $ref: '#/components/responses/Unauthorized' }
/subscriptions/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
operationId: retrieveSubscription
tags: [Subscriptions]
summary: Retrieve a subscription
responses:
'200':
description: The requested subscription.
content:
application/json:
schema: { $ref: '#/components/schemas/Subscription' }
'401': { $ref: '#/components/responses/Unauthorized' }
/usage_items:
post:
operationId: createUsageItem
tags: [Subscriptions]
summary: Record a usage item on a subscription
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [subscription]
properties:
subscription: { type: string }
quantity: { type: integer }
responses:
'200':
description: The created usage item.
content:
application/json:
schema:
type: object
properties:
id: { type: string }
object: { type: string, example: usage_item }
subscription: { type: string }
quantity: { type: integer }
'401': { $ref: '#/components/responses/Unauthorized' }
/payouts:
get:
operationId: listPayouts
tags: [Payouts]
summary: List payouts
responses:
'200':
description: A list of payouts.
content:
application/json:
schema: { $ref: '#/components/schemas/PayoutList' }
'401': { $ref: '#/components/responses/Unauthorized' }
/payouts/{id}:
parameters:
- { name: id, in: path, required: true, schema: { type: string } }
get:
operationId: retrievePayout
tags: [Payouts]
summary: Retrieve a payout
responses:
'200':
description: The requested payout.
content:
application/json:
schema: { $ref: '#/components/schemas/Payout' }
'401': { $ref: '#/components/responses/Unauthorized' }
/payouts/csv_export:
post:
operationId: exportPayoutsCsv
tags: [Payouts]
summary: Export payouts to CSV
responses:
'200': { description: Export accepted. }
'401': { $ref: '#/components/responses/Unauthorized' }
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic authentication. Use your Octobat secret key as the username
and leave the password empty (curl: -u sk_live_xxx:). Use sk_test_ keys
for test mode and sk_live_ keys for live mode.
responses:
Unauthorized:
description: Authentication failed - missing or invalid secret key.
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
schemas:
Error:
type: object
properties:
error:
type: object
properties:
type: { type: string, example: authentication_error }
message: { type: string }
CustomerCreate:
type: object
properties:
name: { type: string }
email: { type: string, format: email }
billing_address_country: { type: string, description: ISO country code. }
billing_address_zip: { type: string }
billing_address_city: { type: string }
tax_number: { type: string }
Customer:
allOf:
- $ref: '#/components/schemas/CustomerCreate'
- type: object
properties:
id: { type: string }
object: { type: string, example: customer }
created: { type: integer }
CustomerList:
type: object
properties:
object: { type: string, example: list }
data:
type: array
items: { $ref: '#/components/schemas/Customer' }
InvoiceCreate:
type: object
properties:
customer: { type: string, description: Octobat customer ID. }
currency: { type: string, example: EUR }
description: { type: string }
Invoice:
type: object
properties:
id: { type: string }
object: { type: string, example: invoice }
customer: { type: string }
currency: { type: string }
status:
type: string
enum: [draft, confirmed, paid, due, uncollectible, cancelled]
number: { type: string, description: Sequential legal number, assigned on confirm. }
total: { type: integer }
total_tax: { type: integer }
description: { type: string }
created: { type: integer }
InvoiceList:
type: object
properties:
object: { type: string, example: list }
data:
type: array
items: { $ref: '#/components/schemas/Invoice' }
InvoiceItemCreate:
type: object
properties:
currency: { type: string }
gross_amount: { type: integer }
description: { type: string }
tax_evidence: { type: string, description: Tax evidence ID from the Tax Evidence API. }
tax: { type: string }
tax_rate: { type: number }
declare_in_region: { type: string }
product_type: { type: string }
Item:
type: object
properties:
id: { type: string }
object: { type: string, example: item }
invoice: { type: string }
gross_amount: { type: integer }
description: { type: string }
CreditNote:
type: object
properties:
id: { type: string }
object: { type: string, example: credit_note }
customer: { type: string }
invoice: { type: string }
number: { type: string }
currency: { type: string }
total: { type: integer }
CreditNoteList:
type: object
properties:
object: { type: string, example: list }
data:
type: array
items: { $ref: '#/components/schemas/CreditNote' }
TransactionCreate:
type: object
properties:
customer: { type: string }
invoice: { type: string }
payment_recipient: { type: string }
currency: { type: string }
amount: { type: integer }
flow_type: { type: string }
status: { type: string }
Transaction:
allOf:
- $ref: '#/components/schemas/TransactionCreate'
- type: object
properties:
id: { type: string }
object: { type: string, example: transaction }
created: { type: integer }
TransactionList:
type: object
properties:
object: { type: string, example: list }
data:
type: array
items: { $ref: '#/components/schemas/Transaction' }
ProductCreate:
type: object
properties:
name: { type: string }
product_type: { type: string, description: Drives tax categorization. }
description: { type: string }
Product:
allOf:
- $ref: '#/components/schemas/ProductCreate'
- type: object
properties:
id: { type: string }
object: { type: string, example: product }
ProductList:
type: object
properties:
object: { type: string, example: list }
data:
type: array
items: { $ref: '#/components/schemas/Product' }
TaxEvidence:
type: object
properties:
id: { type: string }
object: { type: string, example: tax_evidence }
applied_rate: { type:
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/octobat/refs/heads/main/openapi/octobat-openapi.yml