Ecommerce Data Integration

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

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.

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.

Base URL

https://api.subrite.com/

Authentication

All API requests must include the following headers:

Authorization: Bearer <your-jwt-token>

Endpoints

Create or Update 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.

POST /api/v1/custom-orders

Request Body

{
  "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)
  "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)
}

Response

{
  "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": {}
    }
  ]
}

Error Handling

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

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

Common error codes:

• 400: Bad Request - Invalid input data
• 401: Unauthorized - Invalid or missing authentication
• 403: Forbidden - Insufficient permissions
• 500: Internal Server Error

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 to the API
5. Rate Limiting: Respect API rate limits and implement appropriate throttling

Support

If you need help with the integration, contact the Subrite support team at [email protected].