If your store isn't on Shopify, or you want to send orders from your own system, you can use the OuterSignal API. This guide covers how to get your API key, send your first order, and what to send so your analytics fill in correctly. It also covers the Catalog API for product images and collections, and how to delete a customer's data.

Who this is for: the developer or technical lead connecting your store or order system to OuterSignal.
​

If you lose the key, you can generate a new one from that data source's settings. The old key stops working when you do.

Keep your key private. Never put it in code that runs in a browser or in a public code repository.
​

Send each order as a POST request:

Here's a test you can run right away. Replace your-api-key-here with your key:

If it worked, you'll get a 200 response like this:

Send one order per request. There's no batch endpoint.
​

How we find the person behind an order depends on what address data you have. There are three modes:

Send an address whenever you have one. When the shipping and billing addresses are different, include both. It gives us more to match on.

Zip-only example:

Email-only example:

The required fields are enough to identify a customer. The fields below are what fill in your revenue, product, and customer analytics. The most useful ones are:

Here's a fuller order with the most common fields:

Send products as a lineItems array on the order.

A few things to know:

These fields set the lifetime numbers on customer profiles. Send both totals or neither. If you leave both out, we add up the orders you send, counting each order_id once.

When you do send the totals, the most recent order's totals replace what the profile shows, even if they're lower. So send the customer's current running totals from your system with every order.

Order tags and customer.tags both accept either a list (["wholesale", "priority"]) or a single string. A string is split on pipes ("wholesale|priority"), or on commas if there are no pipes ("wholesale,priority").

tags_imported in the response is the total number of order and customer tags we accepted.

Everything else is optional. The more you send, the more complete your analytics.

All money fields use this shape:

discountApplications item:

refunds item:

customerJourney visit (firstVisit, lastVisit, and each item in moments):

To fix an order, send it again with the same order_id and the complete corrected order, including line items and customer. The new version replaces the old one. Anything you leave out is not carried over from the original, so always send the full order, not just what changed.

Example error responses:

If an address is missing in standard mode, the 400 message reads: "at least one address (shipping_address or billing_address) is required, or send search_type "zip_only" with a customer.zip, or search_type "email_only" with a customer.email".

There's no fixed request-rate limit per key. If you're planning to send a high volume continuously, like a large backfill, let us know first so we can plan for it.

Each request has 8 seconds to process. One that runs longer fails with a 500, so retry it the same way.

Orders don't carry product images. If you don't have a connected Shopify store, send your products and collections with the Catalog API so images appear across your analytics and you can track collections in Product Intelligence.

The product title must match your orders exactly. We match products to order line items by title, character for character. A different spelling, spacing, or capitalization counts as a different product, and its image won't show on your orders.

Response:

skipped lists any products whose title already belongs to a connected Shopify store. Shopify stays the source for those.

Resending a product: the image, type, and tags are replaced, and leaving one out clears it. Variants work differently: a resend only replaces the variants you sent before, and variants we picked up from your orders are always kept. A request that repeats the same id or title twice is rejected with 400.

Each collection has an id, a title (up to 255 characters), and the product_ids in it. Collection IDs follow the same rules as product IDs. Send your products first: any product IDs we don't recognize come back in unknown_product_ids and are left out.

Response:

Resending a collection replaces its product list with the one you send. Collections are saved one at a time in the order you send them, so if a request fails partway, the ones before the failure are saved. It's safe to resend the whole request.

Returns { "data": { "deleted": true } }, or false if no collection had that ID. If Product Intelligence was tracking it, it shows as deleted there.

Product and collection IDs belong to the data source whose key sent them. Two data sources can use the same IDs without affecting each other, and a collection can only include products sent with the same key. Product titles are shared across your whole account, though: one title is one product, whichever data source sent it.

When a customer asks you to delete their data, you can remove their records from OuterSignal with one request. Send their email, phone number, or both. Matching records in your account are deleted, along with their signal data.

You need a separate deletion key. The API key you generate for orders doesn't work here; it returns 401. Contact support to get a deletion key. Send it as Authorization: Bearer your-deletion-key, not X-API-Key.

At least one of email or phone is required. Phone numbers must include the country code, like +15551234567 (E.164 format).

Response (200):

How to read the response:

A request that matches nothing returns 200 with deleted: 0, the same as for someone who was already deleted. The response never shows whether a person exists in another account.

Errors come back with a message and a code, for example {"error": "Rate limit exceeded", "code": "RATE_LIMIT_EXCEEDED"}.

Rate limit: 2,000 requests per hour per key. Only requests that pass the key check and validation count toward it.

Send us a message from the chat bubble in OuterSignal and include the order_id and the full response you got back. That's usually all we need to sort it out quickly.