Skip to content
Space Invoices Documentation

Magento Invoicing

Use the native connector to turn Magento 2 orders into documents. Space Invoices checks your store for new and changed orders about every five minutes, so there is no extension to install. For a custom order-to-invoice integration, see Custom Store Invoicing.

Connect Your Store

You need an entity admin in Space Invoices and an administrator in Magento who can add an integration. The store must be reachable over the public internet at its canonical base URL; redirects are not followed.

  1. Start the connection with the store’s full URL, including any path prefix:
Start a Magento connectiontypescript
const authorization = await sdk.orderIntegrations.authorizeMagento({
  name: "My Magento store",
  store_url: "https://store.example.com",
});

// Paste both URLs into Magento. Treat them like secrets.
console.log("Endpoint URL:", authorization.endpoint_url);
console.log("Identity link URL:", authorization.identity_link_url);
console.log("Authorization ID:", authorization.authorization_id);
Checked with SDK v13.16.0
Start Magento Authorization API →
  1. In Magento admin, open System → Extensions → Integrations and choose Add New Integration. Paste the endpoint_url into Endpoint URL and the identity_link_url into Identity link URL. Both URLs are valid for one hour and act as secrets.
  2. On the API tab, grant Sales → Operations → Orders. Also grant Stores → Settings → All Stores if you want documents in each store view’s language.
  3. Choose Save & Activate, then Allow. Magento opens a window that finishes the connection.
  4. Poll the authorization until it is connected:
Wait for the connectiontypescript
const status = await sdk.orderIntegrations.getMagentoAuthorization("AUTHORIZATION_ID");

if (status.status === "connected") {
  console.log("Connected as integration", status.integration_id);
} else if (status.status === "failed") {
  console.log("Activation failed:", status.failure_reason);
} else {
  console.log("Still waiting:", status.status);
}
Checked with SDK v13.16.0
Get Magento Authorization API →
StatusMeaning
awaiting_credentialsMagento has not sent its credentials yet.
awaiting_activationCredentials received; the activation window has not finished.
connectedThe store is connected and integration_id is set.
failedActivation failed; see failure_reason.
expiredThe hour ran out. Start a new connection.

A failed status carries one of these reasons:

  • missing_permissions: Magento did not allow reading orders. Grant Sales → Operations → Orders.
  • unauthorized: Magento rejected the access it issued.
  • unreachable: Space Invoices could not reach the store’s REST API.
  • token_exchange_failed: Magento did not complete the handshake.

To retry, fix the cause in the integration’s settings in Magento, save, and choose Reauthorize. You don’t need to start over unless the authorization expired.

New connections enable automatic order processing and invoice email. Review the integration’s settings before relying on it. Only one active connection per store URL is allowed; starting another returns 409.

Order Import

Space Invoices polls the store about every five minutes (orders are picked up once they are at least a minute old, so a change shows up about five to six minutes after it happens) and imports orders that were created or changed since the connection was made. Orders created before connecting are not imported automatically. If one changes later, polling ignores it unless it was imported with a historical sync.

To import earlier orders, run a historical sync with an explicit window of at most 90 days (the default is the last seven days):

Import orders placed before connectingtypescript
const result = await sdk.orderIntegrations.syncOrderIntegration("INTEGRATION_ID", {
  updated_since: "2026-09-20T00:00:00Z",
  updated_until: "2026-10-08T00:00:00Z",
});

console.log("Imported:", result.imported, "Updated:", result.updated);

// A large window may stop early. Continue from where it stopped.
if (!result.complete) {
  await sdk.orderIntegrations.syncOrderIntegration("INTEGRATION_ID", {
    cursor: result.next_cursor,
  });
}
Checked with SDK v13.16.0
Sync Integration Orders API →

A sync call handles a limited number of pages. When complete is false, call again with the returned next_cursor. Historical sync doesn’t change where regular polling continues. Imported orders are processed with the integration’s current automation settings, so eligible orders can create, email and fiscalize documents. Review those settings, or turn off automatic processing, before importing.

Order Processing Rules

Magento orders go through the same invoicing flow as Shopify and WooCommerce, with the integration’s usual automation settings:

  • An order counts as paid once Magento reports it fully paid, fulfilled when it is complete, closed or fully shipped, and cancelled when its state is canceled.
  • Online payments, such as card or PayPal, are stored but don’t create, email or fiscalize a document until payment is confirmed.
  • Bank transfer, check or money order and purchase order are treated as bank transfers, and cash on delivery as cash. Both follow your configured pre-payment document flow.
  • A fully refunded or closed order voids its invoice. Partial refunds update the order but don’t void the invoice or create a credit note.

Prices are treated as net, with the tax Magento calculated for each line and for shipping. Orders whose totals don’t add up, for example when store credit, gift cards or an extension fee change the amount charged, are kept with an error instead of being invoiced. Reprocess them with POST /orders/{id}/process after resolving the cause. See Orders API for recovery endpoints.

Disabling and Reconnecting

Disabling the integration stops polling. Re-enabling it continues from the moment of re-enabling and does not import the gap, so run a historical sync for the disabled period.

To replace credentials, for example after revoking the integration in Magento, start a new authorization with reconnect_integration_id set to the existing integration. The integration keeps its settings and order history, and only its credentials change.