Orders
Orders contain purchased lines, tax and financial totals. Read an order after its
checkout has an order_id. Keep exact decimal amounts for accounting.
Examples accept the client from setup.
Read an order and its lines
from decimal import Decimal
from vatly import VatlyClient
def example(client: VatlyClient):
order = client.orders.get("order_example")
lines = [(line.product_type, line.product_id, line.quantity) for line in order.lines]
subscription_ids = [
line.related_resources.subscription_id
for line in order.lines
if line.related_resources is not None
]
refundable = Decimal(order.refundable_subtotal.root.value)
return order.status, lines, subscription_ids, refundable
| Response field | Meaning |
|---|---|
id, status, customer_id | Order identity and payment state |
lines | OrderLine models with id, product_type, product_id, quantity, related_resources |
refundable_subtotal, reversed_subtotal | Money wrappers; read .root.value and .root.currency |
links.customer_invoice | Optional customer invoice link |
testmode, metadata | Mode and custom data |
product_type="subscription_plan" means product_id is a plan ID;
"subscription" means a subscription ID. Never substitute one for the other.
line.related_resources.subscription_id is the subscription associated with a
signup, renewal or immediate-update line. related_resources is None on
historical and unrelated lines. On a signup line, subscription_id is None
until the subscription is available; read the order again later. An ID alone
does not prove activation or entitlement: check the subscription's ownership and
status before granting access.
List orders and request an invoice-details link
from vatly import VatlyClient
def example(client: VatlyClient):
orders = list(client.orders.list_all({"limit": 25}))
link = client.orders.create_invoice_update_link("order_example")
return orders, link.href
The hosted link lets the customer update invoice details. Authorize the order
before returning it. List filters include limit, startingAfter, endingBefore;
see the API reference for resource-specific filters.
Use refunds for reversals and chargebacks for disputes. Ownership comes from your checkout records, not a shared customer ID.