# Ecommerce data integration

**Summary:** Sync orders from your ecommerce platform to Subrite with the custom orders API. Covers credentials, authentication, the create or update order endpoint, error codes and best practices.

- Space: [Developers](https://www.subrite.no/developers)
- Source: https://www.subrite.no/developers/ecommerce-data
- Updated: 2026-09-23
- Markdown index: https://www.subrite.no/developers/llms.txt

This guide explains how to integrate your ecommerce platform with Subrite to sync order data. This integration allows you to:

- Sync order history from your platform to Subrite
- Enable order history viewing for members
- Support analytics and segmentation based on order data

<a id="prerequisites"></a>
## Prerequisites

Before you begin, you'll need:

1. A `sourceId`: a unique identifier for your integration
2. A JWT token: for authenticating API requests
3. Member IDs from Subrite that match your customers

Contact the Subrite team to obtain these credentials.

<a id="api-overview"></a>
## API overview

The Ecommerce Data API allows you to create and update orders in Subrite. Each order must be associated with a valid Subrite member ID.

<a id="base-url"></a>
### Base URL

```text
https://api.subrite.com/
```

<a id="authentication"></a>
### Authentication

All API requests must include the following header:

```text
Authorization: Bearer <your-jwt-token>
```

<a id="endpoints"></a>
## Endpoints

<a id="create-or-update-an-order"></a>
### Create or update an order

Creates a new order or updates an existing one in Subrite. If an order with the same `sourceId` and `sourceRef` already exists, it will be updated.

```text
POST /api/v1/custom-orders
```

<a id="request-body"></a>
#### Request body

```javascript
{
  "sourceId": "string",     // Required: Your integration's source ID
  "sourceRef": "string",    // Required: Your platform's order ID
  "memberId": "string",     // Required: Subrite member ID
  "totalPrice": number,     // Required: Order total before VAT
  "totalPriceVat": number,  // Required: Order total including VAT
  "currency": "string",     // Required: ISO 4217 currency code (ex. NOK, EUR, USD, GBP)
  "orderTime": "datetime",  // Optional: ISO 8601 datetime format
  "items": [               // Required: Array of order items
    {
      "productId": "string",
      "productName": "string",
      "categoryId": "string",
      "categoryName": "string",
      "quantity": number,
      "price": number,
      "priceVat": number,
      "customPropertyValues": {} // Optional: Additional item data (needs setup in Subrite before use)
    }
  ],
  "customPropertyValues": {} // Optional: Additional order data  (needs setup in Subrite before use)
}
```

Order fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `sourceId` | string | Yes | Your integration's source ID |
| `sourceRef` | string | Yes | Your platform's order ID |
| `memberId` | string | Yes | Subrite member ID |
| `totalPrice` | number | Yes | Order total before VAT |
| `totalPriceVat` | number | Yes | Order total including VAT |
| `currency` | string | Yes | ISO 4217 currency code (for example NOK, EUR, USD, GBP) |
| `orderTime` | datetime | No | ISO 8601 datetime format |
| `items` | array | Yes | Array of order items |
| `customPropertyValues` | object | No | Additional order data (needs setup in Subrite before use) |

Each entry in `items` has these fields:

| Field | Type |
| --- | --- |
| `productId` | string |
| `productName` | string |
| `categoryId` | string |
| `categoryName` | string |
| `quantity` | number |
| `price` | number |
| `priceVat` | number |
| `customPropertyValues` | object |

The item `customPropertyValues` field is optional and holds additional item data. It needs setup in Subrite before use.

<a id="response"></a>
#### Response

```javascript
{
  "id": "string",
  "orderTime": "string",
  "memberId": "string",
  "sourceId": "string",
  "sourceRef": "string",
  "totalPrice": number,
  "totalPriceVat": number,
  "currency": "string",
  "customPropertyValues": {},
  "items": [
    {
      "id": "string",
      "sequence": number,
      "productId": "string",
      "productName": "string",
      "categoryId": "string",
      "categoryName": "string",
      "quantity": number,
      "price": number,
      "priceVat": number,
      "customPropertyValues": {}
    }
  ]
}
```

<a id="error-handling"></a>
## Error handling

The API uses standard HTTP status codes and returns error details in the response body:

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}
```

Common error codes:

| Status code | Meaning |
| --- | --- |
| `400` | Bad Request: invalid input data |
| `401` | Unauthorized: invalid or missing authentication |
| `403` | Forbidden: insufficient permissions |
| `500` | Internal Server Error |

<a id="best-practices"></a>
## Best practices

1. **Member ID matching:** Ensure you have a reliable way to match your customers with Subrite member IDs.
2. **Order updates:** Use the same `sourceRef` when updating an existing order.
3. **Error handling:** Implement proper error handling and retry logic.
4. **Data validation:** Validate all data before sending it to the API.
5. **Rate limiting:** Respect API rate limits and implement appropriate throttling.

<a id="support"></a>
## Support

If you need help with the integration, contact the Subrite support team at [support@subrite.no](mailto:support@subrite.no).