Connect your custom ecommerce stack through the ingestion API

Goal

By the end of this guide, your ecommerce back office will push your orders and product catalog into Metrikia through the ingestion API. Your sales will be correlated with your ad campaigns: top products, average order value, new customers and profit on real costs, without a platform like Shopify.

Prerequisites

• An active Metrikia account with access to the settings
• A back office able to send HTTP POST requests in JSON (server to server)
• A few minutes to generate an API key

Step 1: Create an API key with the ingest permission

1. In Metrikia, open /app/settings then the API Keys section
2. Click Generate a new key and name it (for example "Ecommerce ingestion")
3. Check the Ecommerce : Ingest permission
4. Copy the key shown (it starts with mk_live_ and is displayed only once)

Step 2: Push your product catalog

Send your products (variant grain) in batches of 1 to 200 to:

POST https://api.metrikia.io/api/v1/ecommerce/ingest/products
X-API-Key: mk_live_your_key

Body: a JSON object with a products array. Required fields per product: externalProductId, externalVariantId, title, currency. Amounts (priceAmount, unitCostAmount) are integer cents. The unit cost feeds the profit calculation; a cost edited manually in Metrikia is never overwritten by a push.

Step 3: Push your orders

Send your paid orders in batches of 1 to 100 to:

POST https://api.metrikia.io/api/v1/ecommerce/ingest/orders
X-API-Key: mk_live_your_key

Body: a JSON object with an orders array. Contract rules:

• externalOrderId is the idempotency key: resending the same order updates the existing one, never a duplicate
• email OR phone is required (at least one) to link the order to a customer
• All amounts in integer cents, currency as a 3-letter ISO code
• financialStatus: paid, partially_refunded or refunded; refundedAmount is the cumulative refunded amount
• processedAt and updatedAt: full ISO 8601 datetimes
• lines: the order lines (title, quantity, unit price, product identifiers) for the product detail
• attribution (optional): first and last visit UTM, stored as customer context

Step 4: Read the response report

Every push answers 200 with a per-item status and a summary (created, enriched, updated, pending_match, skipped, rejected). An invalid item is rejected with the detail of the failing fields, without stopping the rest of the batch.

Expected result

Your orders and products appear on the Ecommerce page (/app/store) moments after the push: net revenue, average order value, top products, and profit when unit costs are set.

Common problems

401 or 403 on the call

• 401: the key is missing, revoked or expired. Check the X-API-Key header
• 403: the key does not carry the Ecommerce : Ingest permission. Generate a new key with that scope

Order paid through Stripe: enriched and pending_match statuses

If an order was paid through your Metrikia Stripe integration, always push it with its reference (stripePaymentIntentId or stripeCheckoutSessionId). The existing Stripe sale is then enriched with the product lines, the composition and the purchase journey, without ever changing its amounts or creating a duplicate. If the payment is not synced yet, the order goes to pending_match: the attachment is retried automatically every hour for 48 hours, nothing is counted in the meantime. A Stripe-paid order pushed without its reference would be counted twice.

Next step

Cross-reference your sales with your campaigns in ADS to measure your real ROAS. Questions along the way? Ask Diana from the help menu.