Purchase Orders
Purchase Orders
Purchase order management operations.
Create, retrieve, and list purchase orders with flexible querying.
Purchase orders are orders sent by Entities to suppliers and contain line items. They are not tax documents.
The supplier is carried in the customer fields. Lines may omit prices; hide_prices defaults to true when no line has a price.
The Purchase Order object
Attributes
{
"id": "po_6595a27b5d35015c3ef0c402",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"number": "DOC-2025-001",
"date": "2025-03-15T00:00:00.000Z",
"currency_code": "USD",
"issuer": {
"name": "Starward Equipment Co.",
"address": "1 Launchpad Way",
"city": "Cape Canaveral",
"state": "FL",
"post_code": "32920",
"country": "USA",
"country_code": "US",
"tax_number": "59-8765432"
},
"customer_id": "cus_6595a27b5d35015c3ef0c403",
"customer": {
"name": "Horizon Launch Systems Inc.",
"address": "100 Rocket Row",
"city": "Houston",
"state": "TX",
"post_code": "77058",
"country": "USA",
"country_code": "US",
"tax_number": "74-1234567"
},
"items": [
{
"id": "po_item_6595a27b5d35015c3ef0c402",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Ground Station Antenna Array",
"description": "Deep space tracking antenna with 12m dish",
"translations": {
"name": {
"de-DE": "Bodenstations-Antennenanlage"
},
"description": {
"de-DE": "Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"
}
},
"quantity": 2,
"price": 12500,
"gross_price": null,
"taxes": [
{
"rate": 22,
"tax_id": "tax_6595a27b5d35015c3ef0c402"
}
],
"discounts": [],
"type": null,
"unit": null,
"total": 25000,
"total_with_tax": 30500,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {
"project_code": "MSN-2025-001",
"department": "Ground Operations"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z"
},
{
"id": "po_item_6595a27b5d35015c3ef0c403",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Orbital Navigation License",
"description": "Annual software license for orbital trajectory planning",
"translations": {
"name": {
"de-DE": "Orbitale Navigationslizenz"
},
"description": {
"de-DE": "Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"
}
},
"quantity": 1,
"price": 5000,
"gross_price": null,
"taxes": [
{
"rate": 22,
"tax_id": "tax_6595a27b5d35015c3ef0c402"
}
],
"discounts": [],
"type": null,
"unit": null,
"total": 5000,
"total_with_tax": 6100,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {
"license_type": "enterprise",
"seats": "50"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z"
}
],
"note": "Thank you for your order. Equipment ships within 5 business days.",
"translations": {
"note": {
"de-DE": "Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."
},
"footer": {
"de-DE": "Fragen? Kontaktieren Sie billing@starward.example."
},
"signature": {
"de-DE": "Starward Equipment Team"
}
},
"reference": "PO-2025-001",
"total": 30000,
"total_with_tax": 36600,
"total_discount": 0,
"total_converted": null,
"total_with_tax_converted": null,
"shareable_id": null,
"taxes": [
{
"base": 30000,
"rate": 22,
"amount": 6600,
"reverse_charge": false,
"tax_id": null
}
],
"date_year": 2025,
"metadata": {
"project_id": "MSN-2025-001",
"contract_id": "ORB-2024-789"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z",
"voided_at": null,
"deleted_at": null,
"exchange_rate": null,
"rounding_correction": null,
"signature": "{entity_name}",
"date_delivery": "2030-03-15T00:00:00.000Z",
"hide_prices": false,
"is_draft": false,
"creation_source": "standard",
"calculation_mode": "b2b_standard"
}Create a new purchase order
/purchase-ordersCreate a new purchase order with line items.
A purchase order is an order sent to a supplier; the supplier is provided in customer_id or customer. The linked contact is marked as a supplier (a buyer contact becomes both) and a contact created from the inline customer starts as a supplier.
Line prices are optional: a regular line without price, gross_price or item_id is stored with a price of 0, and hide_prices defaults to true when no regular line has a non-zero price.
The purchase order number is auto-generated based on the entity's number format settings.
Set date_delivery to the requested delivery date.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Body parameters
Line items for the purchase order. At least one item is required. A regular line without price, gross_price or item_id (or with a null price) is stored with a price of 0.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.purchaseOrders.create({
items: [
{
name: "Satellite Communication Module",
quantity: 1,
price: 1500
}
]
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "po_6595a27b5d35015c3ef0c3fd",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"number": "2026-00001",
"date": "2026-01-01T00:00:00.000Z",
"currency_code": "USD",
"issuer": {
"name": "Starward Equipment Co.",
"country": "United States",
"country_code": "US"
},
"customer_id": null,
"customer": null,
"items": [
{
"id": "po_item_6595a27b5d35015c3ef0c3fd",
"purchase_order_id": "po_6595a27b5d35015c3ef0c3fd",
"expense_id": null,
"item_id": null,
"name": "Satellite Communication Module",
"description": null,
"translations": {},
"quantity": 1,
"price": 1500,
"gross_price": null,
"taxes": [],
"discounts": [],
"type": null,
"unit": null,
"total": 1500,
"total_with_tax": 1500,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"note": null,
"translations": {},
"reference": null,
"total": 1500,
"total_with_tax": 1500,
"total_discount": 0,
"total_converted": null,
"total_with_tax_converted": null,
"shareable_id": null,
"taxes": [
{
"rate": null,
"tax_id": null,
"base": 1500,
"amount": 0,
"reverse_charge": false
}
],
"date_year": 2026,
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"voided_at": null,
"deleted_at": null,
"exchange_rate": null,
"rounding_correction": null,
"signature": "{entity_name}",
"date_delivery": null,
"hide_prices": false,
"is_draft": false,
"creation_source": "standard",
"calculation_mode": "b2b_standard"
}List all purchase orders
/purchase-ordersRetrieve a paginated list of purchase orders with optional filtering and sorting.
Supports cursor-based pagination, flexible JSON querying with MongoDB-style operators, full-text search, and sorting.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Query parameters
Number of results per request.
Default: 10
Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.
Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.
Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.
Sort by one field or provide a repeated array for multi-column ordering. Prefix a field with - for descending order. When paginating, reuse cursors only with the same effective ordering.
JSON query object for filtering results. Supports MongoDB-style operators.
Array columns (such as an item's categories) compare as sets: a direct value asks whether the list contains it, contains takes an array and requires all of them, in matches any of them, and notIn matches none. Scalar operators such as gt do not apply and are ignored.
Supported operators:
- equals or direct value - Exact match (default)
- gte - Greater than or equal
- lte - Less than or equal
- gt - Greater than
- lt - Less than
- in - Value in array
- notIn - Value not in array
- contains - String contains (case-insensitive)
- startsWith - String starts with
- endsWith - String ends with
- between - Value between two numbers/dates [min, max]
Allowed fields: id, number, customer_id, date, customer, customer.name, customer.email, customer.address, customer.city, customer.country, total, total_with_tax, items.name, items.description, payments.type, payments.date, document_relations.relation_type, document_relations.target_type, metadata, created_at, updated_at, paid_in_full, voided_at
Examples:
- {"total": {"gte": 1000}} - Invoices over 1000
- {"customer.name": {"contains": "Acme"}} - Customer name contains "Acme"
- {"date": {"between": ["2025-01-01", "2025-12-31"]}} - Date range
Full-text search query to filter results across multiple fields.
Searches are case-insensitive and match partial strings.
Searches across all text fields including names, descriptions, addresses, and metadata values.
When true, returns only soft-deleted (trashed) items. Default false excludes deleted items.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.purchaseOrders.list({
limit: 20,
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Pagination metadata including cursors and result counts
{
"data": [
{
"id": "po_6595a27b5d35015c3ef0c402",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"number": "DOC-2025-001",
"date": "2025-03-15T00:00:00.000Z",
"currency_code": "USD",
"issuer": {
"name": "Starward Equipment Co.",
"address": "1 Launchpad Way",
"city": "Cape Canaveral",
"state": "FL",
"post_code": "32920",
"country": "USA",
"country_code": "US",
"tax_number": "59-8765432"
},
"customer_id": "cus_6595a27b5d35015c3ef0c403",
"customer": {
"name": "Horizon Launch Systems Inc.",
"address": "100 Rocket Row",
"city": "Houston",
"state": "TX",
"post_code": "77058",
"country": "USA",
"country_code": "US",
"tax_number": "74-1234567"
},
"items": [
{
"id": "po_item_6595a27b5d35015c3ef0c402",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Ground Station Antenna Array",
"description": "Deep space tracking antenna with 12m dish",
"translations": {
"name": {
"de-DE": "Bodenstations-Antennenanlage"
},
"description": {
"de-DE": "Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"
}
},
"quantity": 2,
"price": 12500,
"gross_price": null,
"taxes": [
{
"rate": 22,
"tax_id": "tax_6595a27b5d35015c3ef0c402"
}
],
"discounts": [],
"type": null,
"unit": null,
"total": 25000,
"total_with_tax": 30500,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {
"project_code": "MSN-2025-001",
"department": "Ground Operations"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z"
},
{
"id": "po_item_6595a27b5d35015c3ef0c403",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Orbital Navigation License",
"description": "Annual software license for orbital trajectory planning",
"translations": {
"name": {
"de-DE": "Orbitale Navigationslizenz"
},
"description": {
"de-DE": "Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"
}
},
"quantity": 1,
"price": 5000,
"gross_price": null,
"taxes": [
{
"rate": 22,
"tax_id": "tax_6595a27b5d35015c3ef0c402"
}
],
"discounts": [],
"type": null,
"unit": null,
"total": 5000,
"total_with_tax": 6100,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {
"license_type": "enterprise",
"seats": "50"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z"
}
],
"note": "Thank you for your order. Equipment ships within 5 business days.",
"translations": {
"note": {
"de-DE": "Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."
},
"footer": {
"de-DE": "Fragen? Kontaktieren Sie billing@starward.example."
},
"signature": {
"de-DE": "Starward Equipment Team"
}
},
"reference": "PO-2025-001",
"total": 30000,
"total_with_tax": 36600,
"total_discount": 0,
"total_converted": null,
"total_with_tax_converted": null,
"shareable_id": null,
"taxes": [
{
"base": 30000,
"rate": 22,
"amount": 6600,
"reverse_charge": false,
"tax_id": null
}
],
"date_year": 2025,
"metadata": {
"project_id": "MSN-2025-001",
"contract_id": "ORB-2024-789"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z",
"voided_at": null,
"deleted_at": null,
"exchange_rate": null,
"rounding_correction": null,
"signature": "{entity_name}",
"date_delivery": "2030-03-15T00:00:00.000Z",
"hide_prices": false,
"is_draft": false,
"creation_source": "standard",
"calculation_mode": "b2b_standard"
},
{
"id": "po_6595a27b5d35015c3ef0c402",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"number": "2026-00003",
"date": "2026-01-01T00:00:00.000Z",
"currency_code": "USD",
"issuer": {
"name": "Starward Equipment Co.",
"country": "United States",
"country_code": "US"
},
"customer_id": null,
"customer": {
"name": "Nebula Propulsion Labs"
},
"items": [
{
"id": "po_item_6595a27b5d35015c3ef0c402",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Replacement parts shipment",
"description": null,
"translations": {},
"quantity": 12,
"price": 0,
"gross_price": null,
"taxes": [],
"discounts": [],
"type": null,
"unit": null,
"total": 0,
"total_with_tax": 0,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"note": null,
"translations": {},
"reference": null,
"total": 0,
"total_with_tax": 0,
"total_discount": 0,
"total_converted": null,
"total_with_tax_converted": null,
"shareable_id": null,
"taxes": [
{
"rate": null,
"tax_id": null,
"base": 0,
"amount": 0,
"reverse_charge": false
}
],
"date_year": 2026,
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"voided_at": null,
"deleted_at": null,
"exchange_rate": null,
"rounding_correction": null,
"signature": "{entity_name}",
"date_delivery": "2030-03-15T00:00:00.000Z",
"hide_prices": true,
"is_draft": false,
"creation_source": "standard",
"calculation_mode": "b2b_standard"
}
],
"pagination": {
"total": 2,
"next_cursor": null,
"prev_cursor": null,
"has_more": false
}
}Get purchase order by ID
/purchase-orders/{id}Retrieve a single purchase order by its unique identifier. Returns the complete purchase order details including all line items, supplier information, and calculated totals.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Purchase order identifier (po_ prefix).
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.purchaseOrders.get("po_6595a27b5d35015c3ef0c402", {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "po_6595a27b5d35015c3ef0c402",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"number": "DOC-2025-001",
"date": "2025-03-15T00:00:00.000Z",
"currency_code": "USD",
"issuer": {
"name": "Starward Equipment Co.",
"address": "1 Launchpad Way",
"city": "Cape Canaveral",
"state": "FL",
"post_code": "32920",
"country": "USA",
"country_code": "US",
"tax_number": "59-8765432"
},
"customer_id": "cus_6595a27b5d35015c3ef0c403",
"customer": {
"name": "Horizon Launch Systems Inc.",
"address": "100 Rocket Row",
"city": "Houston",
"state": "TX",
"post_code": "77058",
"country": "USA",
"country_code": "US",
"tax_number": "74-1234567"
},
"items": [
{
"id": "po_item_6595a27b5d35015c3ef0c402",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Ground Station Antenna Array",
"description": "Deep space tracking antenna with 12m dish",
"translations": {
"name": {
"de-DE": "Bodenstations-Antennenanlage"
},
"description": {
"de-DE": "Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"
}
},
"quantity": 2,
"price": 12500,
"gross_price": null,
"taxes": [
{
"rate": 22,
"tax_id": "tax_6595a27b5d35015c3ef0c402"
}
],
"discounts": [],
"type": null,
"unit": null,
"total": 25000,
"total_with_tax": 30500,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {
"project_code": "MSN-2025-001",
"department": "Ground Operations"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z"
},
{
"id": "po_item_6595a27b5d35015c3ef0c403",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Orbital Navigation License",
"description": "Annual software license for orbital trajectory planning",
"translations": {
"name": {
"de-DE": "Orbitale Navigationslizenz"
},
"description": {
"de-DE": "Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"
}
},
"quantity": 1,
"price": 5000,
"gross_price": null,
"taxes": [
{
"rate": 22,
"tax_id": "tax_6595a27b5d35015c3ef0c402"
}
],
"discounts": [],
"type": null,
"unit": null,
"total": 5000,
"total_with_tax": 6100,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {
"license_type": "enterprise",
"seats": "50"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z"
}
],
"note": "Thank you for your order. Equipment ships within 5 business days.",
"translations": {
"note": {
"de-DE": "Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."
},
"footer": {
"de-DE": "Fragen? Kontaktieren Sie billing@starward.example."
},
"signature": {
"de-DE": "Starward Equipment Team"
}
},
"reference": "PO-2025-001",
"total": 30000,
"total_with_tax": 36600,
"total_discount": 0,
"total_converted": null,
"total_with_tax_converted": null,
"shareable_id": null,
"taxes": [
{
"base": 30000,
"rate": 22,
"amount": 6600,
"reverse_charge": false,
"tax_id": null
}
],
"date_year": 2025,
"metadata": {
"project_id": "MSN-2025-001",
"contract_id": "ORB-2024-789"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z",
"voided_at": null,
"deleted_at": null,
"exchange_rate": null,
"rounding_correction": null,
"signature": "{entity_name}",
"date_delivery": "2030-03-15T00:00:00.000Z",
"hide_prices": false,
"is_draft": false,
"creation_source": "standard",
"calculation_mode": "b2b_standard"
}Update a purchase order
/purchase-orders/{id}Update an existing purchase order.
Creates a version snapshot before applying changes.
Cannot update voided purchase orders.
If items are provided, they replace all existing items.
Send date_delivery: null to clear the requested delivery date; omit it to leave it unchanged.hide_prices only changes when a boolean is sent.
When customer_id points the order at another contact, that contact is marked as a supplier.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Purchase order identifier (po_ prefix).
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.purchaseOrders.update("po_6595a27b5d35015c3ef0c402", {
note: "Please deliver to the loading dock",
change_reason: "Added delivery instructions"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "po_6595a27b5d35015c3ef0c402",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"number": "DOC-2025-001",
"date": "2025-03-15T00:00:00.000Z",
"currency_code": "USD",
"issuer": {
"name": "Starward Equipment Co.",
"address": "1 Launchpad Way",
"city": "Cape Canaveral",
"state": "FL",
"post_code": "32920",
"country": "USA",
"country_code": "US",
"tax_number": "59-8765432"
},
"customer_id": "cus_6595a27b5d35015c3ef0c403",
"customer": {
"name": "Horizon Launch Systems Inc.",
"address": "100 Rocket Row",
"city": "Houston",
"state": "TX",
"post_code": "77058",
"country": "USA",
"country_code": "US",
"tax_number": "74-1234567"
},
"items": [
{
"id": "po_item_6595a27b5d35015c3ef0c402",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Ground Station Antenna Array",
"description": "Deep space tracking antenna with 12m dish",
"translations": {
"name": {
"de-DE": "Bodenstations-Antennenanlage"
},
"description": {
"de-DE": "Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"
}
},
"quantity": 2,
"price": 12500,
"gross_price": null,
"taxes": [
{
"rate": 22,
"tax_id": "tax_6595a27b5d35015c3ef0c402"
}
],
"discounts": [],
"type": null,
"unit": null,
"total": 25000,
"total_with_tax": 30500,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {
"project_code": "MSN-2025-001",
"department": "Ground Operations"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z"
},
{
"id": "po_item_6595a27b5d35015c3ef0c403",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Orbital Navigation License",
"description": "Annual software license for orbital trajectory planning",
"translations": {
"name": {
"de-DE": "Orbitale Navigationslizenz"
},
"description": {
"de-DE": "Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"
}
},
"quantity": 1,
"price": 5000,
"gross_price": null,
"taxes": [
{
"rate": 22,
"tax_id": "tax_6595a27b5d35015c3ef0c402"
}
],
"discounts": [],
"type": null,
"unit": null,
"total": 5000,
"total_with_tax": 6100,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {
"license_type": "enterprise",
"seats": "50"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z"
}
],
"note": "Please deliver to the loading dock",
"translations": {
"note": {
"de-DE": "Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."
},
"footer": {
"de-DE": "Fragen? Kontaktieren Sie billing@starward.example."
},
"signature": {
"de-DE": "Starward Equipment Team"
}
},
"reference": "PO-2025-001",
"total": 30000,
"total_with_tax": 36600,
"total_discount": 0,
"total_converted": null,
"total_with_tax_converted": null,
"shareable_id": null,
"taxes": [
{
"base": 30000,
"rate": 22,
"amount": 6600,
"reverse_charge": false,
"tax_id": null
}
],
"date_year": 2025,
"metadata": {
"project_id": "MSN-2025-001",
"contract_id": "ORB-2024-789"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z",
"voided_at": null,
"deleted_at": null,
"exchange_rate": null,
"rounding_correction": null,
"signature": "{entity_name}",
"date_delivery": "2030-03-15T00:00:00.000Z",
"hide_prices": false,
"is_draft": false,
"creation_source": "standard",
"calculation_mode": "b2b_standard"
}Void a purchase order
/purchase-orders/{id}/voidVoid a purchase order for technical reasons (duplicate, error, etc.). Voiding marks the purchase order as invalid and prevents further modifications.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Purchase order identifier (po_ prefix).
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.purchaseOrders.void("po_6595a27b5d35015c3ef0c402", {
reason: "Duplicate purchase order created by mistake"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "po_6595a27b5d35015c3ef0c402",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"number": "DOC-2025-001",
"date": "2025-03-15T00:00:00.000Z",
"currency_code": "USD",
"issuer": {
"name": "Starward Equipment Co.",
"address": "1 Launchpad Way",
"city": "Cape Canaveral",
"state": "FL",
"post_code": "32920",
"country": "USA",
"country_code": "US",
"tax_number": "59-8765432"
},
"customer_id": "cus_6595a27b5d35015c3ef0c403",
"customer": {
"name": "Horizon Launch Systems Inc.",
"address": "100 Rocket Row",
"city": "Houston",
"state": "TX",
"post_code": "77058",
"country": "USA",
"country_code": "US",
"tax_number": "74-1234567"
},
"items": [
{
"id": "po_item_6595a27b5d35015c3ef0c402",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Ground Station Antenna Array",
"description": "Deep space tracking antenna with 12m dish",
"translations": {
"name": {
"de-DE": "Bodenstations-Antennenanlage"
},
"description": {
"de-DE": "Tiefraum-Tracking-Antenne mit 12-m-Parabolspiegel"
}
},
"quantity": 2,
"price": 12500,
"gross_price": null,
"taxes": [
{
"rate": 22,
"tax_id": "tax_6595a27b5d35015c3ef0c402"
}
],
"discounts": [],
"type": null,
"unit": null,
"total": 25000,
"total_with_tax": 30500,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {
"project_code": "MSN-2025-001",
"department": "Ground Operations"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z"
},
{
"id": "po_item_6595a27b5d35015c3ef0c403",
"purchase_order_id": "po_6595a27b5d35015c3ef0c402",
"expense_id": null,
"item_id": null,
"name": "Orbital Navigation License",
"description": "Annual software license for orbital trajectory planning",
"translations": {
"name": {
"de-DE": "Orbitale Navigationslizenz"
},
"description": {
"de-DE": "Jaehrliche Softwarelizenz fuer die Planung von Orbitaltrajektorien"
}
},
"quantity": 1,
"price": 5000,
"gross_price": null,
"taxes": [
{
"rate": 22,
"tax_id": "tax_6595a27b5d35015c3ef0c402"
}
],
"discounts": [],
"type": null,
"unit": null,
"total": 5000,
"total_with_tax": 6100,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {
"license_type": "enterprise",
"seats": "50"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z"
}
],
"note": "Thank you for your order. Equipment ships within 5 business days.",
"translations": {
"note": {
"de-DE": "Vielen Dank fuer Ihre Bestellung. Die Ausruestung wird innerhalb von 5 Werktagen versendet."
},
"footer": {
"de-DE": "Fragen? Kontaktieren Sie billing@starward.example."
},
"signature": {
"de-DE": "Starward Equipment Team"
}
},
"reference": "PO-2025-001",
"total": 30000,
"total_with_tax": 36600,
"total_discount": 0,
"total_converted": null,
"total_with_tax_converted": null,
"shareable_id": null,
"taxes": [
{
"base": 30000,
"rate": 22,
"amount": 6600,
"reverse_charge": false,
"tax_id": null
}
],
"date_year": 2025,
"metadata": {
"project_id": "MSN-2025-001",
"contract_id": "ORB-2024-789"
},
"created_at": "2025-03-15T00:00:00.000Z",
"updated_at": "2025-03-15T00:00:00.000Z",
"voided_at": "2026-01-20T12:00:00.000Z",
"deleted_at": null,
"exchange_rate": null,
"rounding_correction": null,
"signature": "{entity_name}",
"date_delivery": "2030-03-15T00:00:00.000Z",
"hide_prices": false,
"is_draft": false,
"creation_source": "standard",
"calculation_mode": "b2b_standard"
}Get purchase order version history
/purchase-orders/{id}/versionsRetrieve the version history for a purchase order. Each version represents the document state before an update was applied.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Purchase order identifier (po_ prefix).
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.purchaseOrders.getVersions("po_6595a27b5d35015c3ef0c402", {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"versions": [
{
"id": "ver_abc123",
"document_type": "purchase_order",
"document_id": "po_6595a27b5d35015c3ef0c3fd",
"version": 2,
"snapshot": {
"id": "po_6595a27b5d35015c3ef0c3fd",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"number": "2026-00001",
"date": "2026-01-01T00:00:00.000Z",
"currency_code": "USD",
"issuer": {
"name": "Starward Equipment Co.",
"country": "United States",
"country_code": "US"
},
"customer_id": null,
"customer": null,
"items": [
{
"id": "po_item_6595a27b5d35015c3ef0c3fd",
"purchase_order_id": "po_6595a27b5d35015c3ef0c3fd",
"expense_id": null,
"item_id": null,
"name": "Satellite Communication Module",
"description": null,
"translations": {},
"quantity": 1,
"price": 1500,
"gross_price": null,
"taxes": [],
"discounts": [],
"type": null,
"unit": null,
"total": 1500,
"total_with_tax": 1500,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"note": null,
"translations": {},
"reference": null,
"total": 1500,
"total_with_tax": 1500,
"total_discount": 0,
"total_converted": null,
"total_with_tax_converted": null,
"shareable_id": null,
"taxes": [
{
"rate": null,
"tax_id": null,
"base": 1500,
"amount": 0,
"reverse_charge": false
}
],
"date_year": 2026,
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"voided_at": null,
"deleted_at": null,
"exchange_rate": null,
"rounding_correction": null,
"signature": "{entity_name}",
"date_delivery": null,
"hide_prices": false,
"is_draft": false,
"creation_source": "standard",
"calculation_mode": "b2b_standard"
},
"changed_fields": [
"note"
],
"user": {
"id": "usr_123",
"name": "Alex Carter",
"email": "alex.carter@starward.example"
},
"reason": "Added delivery instructions",
"created_at": "2025-01-15T10:30:00.000Z"
},
{
"id": "ver_xyz789",
"document_type": "purchase_order",
"document_id": "po_6595a27b5d35015c3ef0c3fd",
"version": 1,
"snapshot": {
"id": "po_6595a27b5d35015c3ef0c3fd",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"number": "2026-00001",
"date": "2026-01-01T00:00:00.000Z",
"currency_code": "USD",
"issuer": {
"name": "Starward Equipment Co.",
"country": "United States",
"country_code": "US"
},
"customer_id": null,
"customer": null,
"items": [
{
"id": "po_item_6595a27b5d35015c3ef0c3fd",
"purchase_order_id": "po_6595a27b5d35015c3ef0c3fd",
"expense_id": null,
"item_id": null,
"name": "Satellite Communication Module",
"description": null,
"translations": {},
"quantity": 1,
"price": 1500,
"gross_price": null,
"taxes": [],
"discounts": [],
"type": null,
"unit": null,
"total": 1500,
"total_with_tax": 1500,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"note": null,
"translations": {},
"reference": null,
"total": 1500,
"total_with_tax": 1500,
"total_discount": 0,
"total_converted": null,
"total_with_tax_converted": null,
"shareable_id": null,
"taxes": [
{
"rate": null,
"tax_id": null,
"base": 1500,
"amount": 0,
"reverse_charge": false
}
],
"date_year": 2026,
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"voided_at": null,
"deleted_at": null,
"exchange_rate": null,
"rounding_correction": null,
"signature": "{entity_name}",
"date_delivery": null,
"hide_prices": false,
"is_draft": false,
"creation_source": "standard",
"calculation_mode": "b2b_standard"
},
"changed_fields": [
"items"
],
"user": {
"id": "usr_123",
"name": "Alex Carter",
"email": "alex.carter@starward.example"
},
"reason": "Revised item list",
"created_at": "2025-01-14T15:00:00.000Z"
}
],
"count": 2
}Get specific purchase order version
/purchase-orders/{id}/versions/{version}Retrieve a specific version snapshot of a purchase order.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Purchase order identifier (po_ prefix).
Version number
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.purchaseOrders.getVersion("po_6595a27b5d35015c3ef0c402", 1, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Version record ID
{
"id": "ver_abc123",
"document_type": "purchase_order",
"document_id": "po_6595a27b5d35015c3ef0c3fd",
"version": 1,
"snapshot": {
"id": "po_6595a27b5d35015c3ef0c3fd",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"number": "2026-00001",
"date": "2026-01-01T00:00:00.000Z",
"currency_code": "USD",
"issuer": {
"name": "Starward Equipment Co.",
"country": "United States",
"country_code": "US"
},
"customer_id": null,
"customer": null,
"items": [
{
"id": "po_item_6595a27b5d35015c3ef0c3fd",
"purchase_order_id": "po_6595a27b5d35015c3ef0c3fd",
"expense_id": null,
"item_id": null,
"name": "Satellite Communication Module",
"description": null,
"translations": {},
"quantity": 1,
"price": 1500,
"gross_price": null,
"taxes": [],
"discounts": [],
"type": null,
"unit": null,
"total": 1500,
"total_with_tax": 1500,
"total_converted": null,
"total_with_tax_converted": null,
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"note": null,
"translations": {},
"reference": null,
"total": 1500,
"total_with_tax": 1500,
"total_discount": 0,
"total_converted": null,
"total_with_tax_converted": null,
"shareable_id": null,
"taxes": [
{
"rate": null,
"tax_id": null,
"base": 1500,
"amount": 0,
"reverse_charge": false
}
],
"date_year": 2026,
"metadata": {},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"voided_at": null,
"deleted_at": null,
"exchange_rate": null,
"rounding_correction": null,
"signature": "{entity_name}",
"date_delivery": null,
"hide_prices": false,
"is_draft": false,
"creation_source": "standard",
"calculation_mode": "b2b_standard"
},
"changed_fields": [
"items"
],
"user": {
"id": "usr_123",
"name": "Alex Carter",
"email": "alex.carter@starward.example"
},
"reason": "Revised item list",
"created_at": "2025-01-14T15:00:00.000Z"
}Preview next document number
/documents/next-numberPreview the next auto-generated document number for the specified type without incrementing the sequence. Useful for showing users what number will be assigned before creating a document.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Query parameters
Document type
Possible values: "invoice", "estimate", "credit_note", "advance_invoice", "delivery_note", "purchase_order"
Optional business unit scope for unit-specific numbering sequences.
Business premise name (FURS or FINA). If provided with electronic_device_name, returns fiscalization-format number.
Electronic device name (FURS or FINA). Required if business_premise_name is provided. When provided, returns fiscalization-format number.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.documents.getNextNumber({
type: "invoice"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"number": "2026-00042",
"furs": null
}Render purchase order preview
/purchase-orders/renderRender an HTML preview of a purchase order without saving to the database. Perfect for displaying live previews in purchase order creation/edit forms. Lines without a price render with a price of 0, like on creation. Supports both partial mode (allows incomplete data for drafts) and complete mode (validates all required fields).
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Query parameters
Document template design to use. When not specified, uses the entity's configured template.
Possible values: "modern", "classic", "condensed", "minimal", "fashion"
Locale for number and date formatting (decimal separators, date order). When not specified, uses the entity's configured locale. For example, 'sl-SI' formats decimals with commas (5,5%) and dates as DD. MM. YYYY.
Language for document labels and translations (e.g., 'Invoice', 'Tax', 'Total'). When not specified, uses the same value as locale. Use this to get entity-locale formatting with different-language labels — for example, a Slovenian entity (sl-SI formatting with commas) but English labels.
Whether to treat the document as partial (allows incomplete data) or complete (validates all required fields)
Possible values: "true", "false"
Default: "true"
Override UPN QR enabled setting for preview
Possible values: "true", "false"
Override UPN QR display mode for preview
Possible values: "qr_only", "full_slip"
Override EPC QR enabled setting for preview
Possible values: "true", "false"
Override Croatian HUB3 PDF417 barcode enabled setting for preview
Possible values: "true", "false"
Override HUB3 purpose code for preview
Override HUB3 Croatian reference model for preview
Override Swiss QR-bill enabled setting for preview
Possible values: "true", "false"
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.purchaseOrders.renderPurchaseOrderPreview({
items: [
{
name: "Titanium bolts",
quantity: 120
}
],
customer: {
name: "Orbital Supplies Ltd"
},
date_delivery: "2030-03-15"
}, undefined, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Preview document calculation
/documents/calculateCalculate document totals, taxes, and transaction type without creating the document. Useful for showing live totals in forms or validating data before submission.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Query parameters
Document type
Possible values: "invoice", "estimate", "credit_note", "advance_invoice", "delivery_note", "purchase_order"
Body parameters
Document line items to calculate. At least one item is required.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.documents.calculateDocumentPreview({
items: [
{
name: "Web Development",
quantity: 10,
price: 100,
taxes: [
{
rate: 22
}
]
}
]
}, {
type: "invoice"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"items": [
{
"name": "Web Development",
"description": null,
"type": null,
"price": 100,
"gross_price": null,
"quantity": 10,
"unit": null,
"taxes": [
{
"name": "VAT",
"rate": 22,
"base": 1000,
"amount": 220
}
],
"discounts": [],
"total": 1000,
"total_with_tax": 1220,
"total_converted": null,
"total_with_tax_converted": null
}
],
"total": 1000,
"total_with_tax": 1220,
"total_discount": 0,
"taxes": [
{
"name": "VAT",
"rate": 22,
"base": 1000,
"amount": 220,
"reverse_charge": false
}
],
"transaction_type": "domestic",
"currency_code": "EUR",
"exchange_rate": null,
"total_converted": null,
"total_with_tax_converted": null,
"rounding_correction": null,
"vies": null
}Finalize a draft document
/documents/{id}/finalizeFinalize a draft document by assigning a document number, running fiscalization (if applicable), and optionally sending it electronically. Only draft documents can be finalized. Draft advance invoices must first have payments covering their full total. After finalization, the document cannot be deleted. For a Hungarian invoice, credit note or advance invoice whose entity has NAV dispatch enabled, finalizing maps it to a NAV Online Számla submission; data that cannot be mapped responds 422 NAV_INVOICE_DATA_INVALID with an issues array.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Document ID
Query parameters
Document type. Optional — automatically inferred from the document ID prefix.
Possible values: "invoice", "estimate", "credit_note", "advance_invoice", "delivery_note", "purchase_order"
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.documents.finalizeDocument("inv_clx1234567890", {
e_invoicing: {
send_enabled: true
}
}, undefined, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);nullDelete a draft document
/documents/{id}Delete a draft document. Only draft documents can be deleted. Finalized documents cannot be deleted - use void instead.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Document ID
Query parameters
Document type. Optional — automatically inferred from the document ID prefix.
Possible values: "invoice", "estimate", "credit_note", "advance_invoice", "delivery_note", "purchase_order"
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
await sdk.documents.delete("inv_clx1234567890", undefined, {
entity_id: "YOUR_ENTITY_ID"
});
console.log('Deleted successfully');Permanently delete a document
/documents/{id}/permanentPermanently delete a soft-deleted document. Only documents in the trash can be permanently deleted. Only draft documents and estimates can be permanently deleted.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Document ID
Query parameters
Document type. Optional — automatically inferred from the document ID prefix.
Possible values: "invoice", "estimate", "credit_note", "advance_invoice", "delivery_note", "purchase_order"
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
await sdk.documents.permanentDeleteDocument("inv_clx1234567890", undefined, {
entity_id: "YOUR_ENTITY_ID"
});
console.log('Deleted successfully');Restore a deleted document
/documents/{id}/restoreRestore a soft-deleted document from the trash. The document will be returned to its original state.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Document ID
Query parameters
Document type. Optional — automatically inferred from the document ID prefix.
Possible values: "invoice", "estimate", "credit_note", "advance_invoice", "delivery_note", "purchase_order"
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.documents.restoreDocument("inv_clx1234567890", undefined, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);null