Order Integrations
Order Integrations
Manage connections to external e-commerce platforms.
Connect Shopify, WooCommerce, Magento, or your own custom store to automatically receive and process orders into invoices.
The Order Integration object
Attributes
{
"id": "oint_6595a27b5d35015c3ef0c3fd",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"name": "Horizon Launch Store",
"source": "manual",
"is_active": true,
"shop_domain": null,
"scopes": null,
"auto_process": true,
"auto_process_on": "created",
"default_payment_type": null,
"send_invoice_email": true,
"send_estimate_email": true,
"attach_pdf_to_email": false,
"issue_invoice_for_bank": false,
"issue_invoice_on_complete": false,
"auto_process_delay_seconds": 0,
"document_currency": "checkout",
"auto_reissue_on_update": false,
"classify_imported_items_as_products": false,
"buyer_language_item_names": false,
"metadata": {},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-09-01T00:00:00.000Z",
"deleted_at": null
}Resume Shopify install after app launch
/order-integrations/shopify/resume-installContinue a pending Shopify install after Shopify redirects the merchant back to the app URL.
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.orderIntegrations.resumeShopifyInstall({
shop: "myshop.myshopify.com"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"redirect_url": "https://myshop.myshopify.com/admin/oauth/authorize?client_id=...&scope=read_orders&redirect_uri=...&state=...",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"frontend_origin": "https://v2.getapollo.io"
}Connect a custom store
/order-integrations/custom/connectCreate an integration for your own online store. The response contains the webhook URL and the signing secret, which is shown only once. Your store then sends orders as signed webhooks or with the push order endpoint, and they are processed like Shopify and WooCommerce orders.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Body parameters
Integration name
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.orderIntegrations.connectCustomStore({
name: "Horizon Launch Webshop"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"integration": {
"id": "oint_6595a27b5d35015c3ef0c3fd",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"name": "Horizon Launch Webshop",
"source": "custom",
"is_active": true,
"shop_domain": null,
"scopes": null,
"auto_process": true,
"auto_process_on": "created",
"default_payment_type": null,
"send_invoice_email": true,
"send_estimate_email": true,
"attach_pdf_to_email": false,
"issue_invoice_for_bank": false,
"issue_invoice_on_complete": false,
"auto_process_delay_seconds": 0,
"document_currency": "checkout",
"auto_reissue_on_update": false,
"classify_imported_items_as_products": false,
"buyer_language_item_names": false,
"metadata": {
"custom_store_connected_at": "2026-10-01T09:00:00.000Z"
},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-09-01T00:00:00.000Z",
"deleted_at": null,
"store_url": "https://shop.horizon-launch.com"
},
"webhook_url": "https://eu.spaceinvoices.com/v1/webhooks/orders/oint_6595a27b5d35015c3ef0c3fd",
"signing_secret": "whsec_6qPb2Tr3UJbq2l0c3S8a1o2xg3HhK8m4Yd9Vf0nJ7wE"
}Create a new order integration
/order-integrationsCreate a new order integration for receiving orders from external platforms. New integrations start ready to use: automatic processing is on and documents are created when an order arrives. Pass auto_process: false to review orders before processing.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.orderIntegrations.create({
name: "Horizon Launch Store"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "oint_6595a27b5d35015c3ef0c3fd",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"name": "Horizon Launch Store",
"source": "manual",
"is_active": true,
"shop_domain": null,
"scopes": null,
"auto_process": true,
"auto_process_on": "created",
"default_payment_type": null,
"send_invoice_email": true,
"send_estimate_email": true,
"attach_pdf_to_email": false,
"issue_invoice_for_bank": false,
"issue_invoice_on_complete": false,
"auto_process_delay_seconds": 0,
"document_currency": "checkout",
"auto_reissue_on_update": false,
"classify_imported_items_as_products": false,
"buyer_language_item_names": false,
"metadata": {},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-09-01T00:00:00.000Z",
"deleted_at": null
}List all order integrations
/order-integrationsRetrieve a paginated list of order integrations with optional filtering 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, name, source, is_active, created_at, updated_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.orderIntegrations.list({
limit: 20,
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
Pagination metadata including cursors and result counts
{
"data": [
{
"id": "oint_6595a27b5d35015c3ef0c3fd",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"name": "Horizon Launch Store",
"source": "manual",
"is_active": true,
"shop_domain": null,
"scopes": null,
"auto_process": true,
"auto_process_on": "created",
"default_payment_type": null,
"send_invoice_email": true,
"send_estimate_email": true,
"attach_pdf_to_email": false,
"issue_invoice_for_bank": false,
"issue_invoice_on_complete": false,
"auto_process_delay_seconds": 0,
"document_currency": "checkout",
"auto_reissue_on_update": false,
"classify_imported_items_as_products": false,
"buyer_language_item_names": false,
"metadata": {},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-09-01T00:00:00.000Z",
"deleted_at": null
}
],
"pagination": {
"total": 1,
"next_cursor": null,
"prev_cursor": null,
"has_more": false
}
}Get order integration by ID
/order-integrations/{id}Retrieve a single order integration by its unique identifier.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.orderIntegrations.get('ORDERINTEGRATIONS_ID', {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "oint_6595a27b5d35015c3ef0c3fd",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"name": "Horizon Launch Store",
"source": "manual",
"is_active": true,
"shop_domain": null,
"scopes": null,
"auto_process": true,
"auto_process_on": "created",
"default_payment_type": null,
"send_invoice_email": true,
"send_estimate_email": true,
"attach_pdf_to_email": false,
"issue_invoice_for_bank": false,
"issue_invoice_on_complete": false,
"auto_process_delay_seconds": 0,
"document_currency": "checkout",
"auto_reissue_on_update": false,
"classify_imported_items_as_products": false,
"buyer_language_item_names": false,
"metadata": {},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-09-01T00:00:00.000Z",
"deleted_at": null
}Update an order integration
/order-integrations/{id}Update an existing order integration. Only the provided fields will be updated. Disabling Shopify persists the inactive state before remote webhook cleanup; a 502 means cleanup remains pending and the same disable request can be retried safely. Re-enabling restores webhooks before activation and records a crash-recoverable catch-up boundary after activation commits.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.orderIntegrations.update('ORDERINTEGRATIONS_ID', {
name: "Horizon Launch Store EU"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"id": "oint_6595a27b5d35015c3ef0c3fd",
"entity_id": "ent_6595a27b5d35015c3ef0c3fd",
"name": "Horizon Launch Store",
"source": "manual",
"is_active": true,
"shop_domain": null,
"scopes": null,
"auto_process": true,
"auto_process_on": "created",
"default_payment_type": null,
"send_invoice_email": true,
"send_estimate_email": true,
"attach_pdf_to_email": false,
"issue_invoice_for_bank": false,
"issue_invoice_on_complete": false,
"auto_process_delay_seconds": 0,
"document_currency": "checkout",
"auto_reissue_on_update": false,
"classify_imported_items_as_products": false,
"buyer_language_item_names": false,
"metadata": {},
"created_at": "2024-01-01T00:00:00.000Z",
"updated_at": "2024-09-01T00:00:00.000Z",
"deleted_at": null
}Delete an order integration
/order-integrations/{id}Soft delete an order integration. Shopify integrations are first made inactive, then their owned webhooks are removed. A 502 leaves the integration inactive with cleanup pending; repeat the delete request safely to retry cleanup.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
await sdk.orderIntegrations.delete('ORDERINTEGRATIONS_ID', {
entity_id: "YOUR_ENTITY_ID"
});
console.log('Deleted successfully');Promote an additional Shopify store to primary billing
/order-integrations/{id}/promote-shopify-billingStarts Shopify approval for the designated promotion candidate after the former primary store is uninstalled. The replacement primary subscription has no repeated trial.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.orderIntegrations.promoteShopifyBilling('ORDERINTEGRATIONS_ID', {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"redirect_url": "https://example.com"
}Sync Shopify orders
/order-integrations/{id}/sync-shopifyFetch Shopify orders updated in the selected time window and upsert them into local orders. Missing orders are imported, existing orders are refreshed, and processing is queued separately. Existing clients retain one-request completion; set resumable=true to opt into bounded chunks, then repeat completion_state=resumable responses with next_cursor. Disabled-period checkpoints are persisted so repeated safe requests durably converge. Shopify throttling is retried twice with each wait capped at five seconds; an exhausted throttle returns 429 with Retry-After. If Shopify expires a stored REST page cursor, the server safely clears that checkpoint and restarts the exact window; idempotent event IDs make the replay safe.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique resource identifier. Prefix depends on the resource, for example inv_, cus_, or ent_.
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.orderIntegrations.syncShopifyOrders('ORDERINTEGRATIONS_ID', {}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"imported": 12,
"updated": 4,
"queued_for_processing": 6,
"total_seen": 16,
"window_start": "2026-03-20T00:00:00.000Z",
"window_end": "2026-03-21T00:00:00.000Z",
"complete": true,
"truncated": false,
"pages_fetched": 1,
"completion_state": "complete"
}Sync integration orders
/order-integrations/{id}/syncFetch a bounded historical window from the connected provider. Incomplete WooCommerce and Magento windows return a signed continuation cursor.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique order integration identifier
Body parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.orderIntegrations.syncOrderIntegration("oint_6595a27b5d35015c3ef0c3fd", {
updated_since: "2026-08-01T00:00:00.000Z",
updated_until: "2026-08-07T00:00:00.000Z",
limit: 100
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"imported": 8,
"updated": 2,
"queued_for_processing": 4,
"total_seen": 10,
"window_start": "2026-08-01T00:00:00.000Z",
"window_end": "2026-08-07T00:00:00.000Z",
"complete": true,
"truncated": false,
"pages_fetched": 1,
"completion_state": "complete"
}Rotate a custom store signing secret
/order-integrations/{id}/custom/rotate-secretIssue a new signing secret for a custom store. The previous secret keeps verifying webhooks for 24 hours so you can update your store without dropping orders.
Header parameters
Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.
Path parameters
Unique order integration identifier
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.orderIntegrations.rotateCustomStoreSecret("oint_6595a27b5d35015c3ef0c3fd", {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"webhook_url": "https://eu.spaceinvoices.com/v1/webhooks/orders/oint_6595a27b5d35015c3ef0c3fd",
"signing_secret": "whsec_6qPb2Tr3UJbq2l0c3S8a1o2xg3HhK8m4Yd9Vf0nJ7wE"
}Push a custom store order
/order-integrations/{id}/ordersCreate or update an order from a custom store with your API key instead of a signed webhook. Send the full current order each time; repeated pushes with the same order id update it, and documents, emails and refunds follow the integration settings. Always include a stable event_id per logical event (e.g. 1043:paid) and reuse it on retries: without one, a retried earlier push is applied again and can overwrite newer 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
Unique order integration identifier
Body parameters
Your store's unique order ID. Repeated pushes update the same order.
Order total the buyer pays. Lines must reconcile to it within rounding: 0.02, or half a cent per line for larger orders.
import SpaceInvoices from '@spaceinvoices/js-sdk/sdk';
const sdk = new SpaceInvoices('YOUR_API_KEY');
const response = await sdk.orderIntegrations.pushCustomStoreOrder("oint_6595a27b5d35015c3ef0c3fd", {
id: "1042",
event_id: "1042:created",
order_number: "#1042",
currency_code: "EUR",
prices_include_tax: true,
total_with_tax: 61,
ordered_at: "2026-10-01T09:30:00Z",
locale: "sl-SI",
customer: {
name: "Alex Rivera",
email: "alex.rivera@example.com"
},
billing_address: {
address: "Slovenska cesta 1",
city: "Ljubljana",
post_code: "1000",
country_code: "SI"
},
items: [
{
name: "Mission Patch Set - Apollo Edition",
sku: "PATCH-APOLLO",
quantity: 2,
unit_price: 24.4,
tax_rate: 22
},
{
kind: "shipping",
name: "Express delivery",
quantity: 1,
unit_price: 12.2,
tax_rate: 22
}
],
payment_method: "card",
payment_reference: "pi_3PZ0abc",
paid: true,
paid_at: "2026-10-01T09:31:00Z"
}, {
entity_id: "YOUR_ENTITY_ID"
});
console.log(response);Returns
{
"order_id": "ord_6595a27b5d35015c3ef0c3fd",
"action": "created",
"processing_queued": true
}