Guide

Field Mapping Guide

Learn how to map your data fields to the Regen Therapy API for seamless order processing.

Overview

Field mapping allows you to use your own product identifiers (SKUs), customer IDs, and shipping methods while the API automatically translates them to our platform format. This is essential for:

Private Labels

Use your own brand names and SKUs for white-label products while we handle fulfillment.

System Integration

Connect your existing e-commerce platform without changing your internal product codes.

Error Prevention

Validate orders before submission to catch SKU mismatches and field errors early.

Quick Start

Step 1: Discover the Schema

Use the Schema API to see all available fields for orders, products, and inventory.

curl -X GET "https://gateway.regentherapy.com/api/v1/schema/order?grouped=true" \
  -H "X-API-Key: your_api_key"

The response shows all fields organized by category (core, customer, shipping, payment, metadata) with validation rules and example values.

Step 2: Create SKU Mappings

Map your product SKUs to our platform products.

curl -X POST "https://gateway.regentherapy.com/api/v1/mappings/skus" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalSku": "MY-CBD-1000",
    "platformSku": "CBD-OIL-1000-FS",
    "externalName": "Wellness CBD Oil 1000mg",
    "isPrivateLabel": true
  }'

Step 3: Validate Before Submitting

Use the validation endpoint to check your order before creating it.

curl -X POST "https://gateway.regentherapy.com/api/v1/orders/validate" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOrderId": "ORD-12345",
    "items": [
      { "sku": "MY-CBD-1000", "quantity": 2 }
    ],
    "customer": {
      "email": "customer@example.com",
      "firstName": "John",
      "lastName": "Smith"
    },
    "shippingAddress": {
      "line1": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701",
      "country": "US"
    }
  }'

SKU Mapping

SKU mapping is the core of field mapping. It allows you to submit orders using your own product codes while we automatically resolve them to the correct platform products.

How SKU Resolution Works

When you submit an order, the API resolves SKUs in this order:

Tenant SKU Mappings - Checks your custom SKU mappings first
Private Label Mappings - Checks existing private label product mappings
Direct Platform SKU - Falls back to exact platform SKU match

Priority Matters

If you have multiple mappings for the same external SKU, set the priority field to control which one is used.

Bulk Import SKU Mappings

Import up to 500 SKU mappings in a single request.

curl -X POST "https://gateway.regentherapy.com/api/v1/mappings/skus/bulk" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "updateExisting": true,
    "mappings": [
      {
        "externalSku": "MY-CBD-500",
        "platformSku": "CBD-OIL-500-FS",
        "externalName": "Wellness CBD 500mg"
      },
      {
        "externalSku": "MY-CBD-1000",
        "platformSku": "CBD-OIL-1000-FS",
        "externalName": "Wellness CBD 1000mg",
        "priceOverride": 59.99
      },
      {
        "externalSku": "MY-GUMMY-30",
        "platformSku": "CBD-GUMMY-30CT",
        "isPrivateLabel": true
      }
    ]
  }'

Set updateExisting: true to update mappings that already exist. Otherwise, existing mappings will be skipped.

Resolve SKUs Before Ordering

Test your SKU mappings without creating an order.

curl -X POST "https://gateway.regentherapy.com/api/v1/mappings/skus/resolve" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "skus": ["MY-CBD-500", "MY-CBD-1000", "UNKNOWN-SKU"]
  }'

{
  "success": true,
  "data": {
    "summary": {
      "total": 3,
      "resolved": 2,
      "unresolved": 1,
      "allResolved": false
    },
    "results": [
      {
        "externalSku": "MY-CBD-500",
        "resolved": true,
        "platformSku": "CBD-OIL-500-FS",
        "platformProductId": "prod_abc123",
        "productName": "Wellness CBD 500mg",
        "productPrice": 39.99,
        "productActive": true
      },
      {
        "externalSku": "MY-CBD-1000",
        "resolved": true,
        "platformSku": "CBD-OIL-1000-FS",
        "platformProductId": "prod_def456",
        "productName": "Wellness CBD 1000mg",
        "productPrice": 69.99,
        "priceOverride": 59.99,
        "productActive": true
      },
      {
        "externalSku": "UNKNOWN-SKU",
        "resolved": false,
        "error": "SKU 'UNKNOWN-SKU' not found in mappings or product catalog"
      }
    ]
  }
}

Order Validation

The validation endpoint performs a complete dry-run of your order, checking all fields, resolving SKUs, and verifying inventory without creating any data.

Always Validate First

We strongly recommend validating orders before submission, especially when integrating new systems. The validation endpoint catches errors that would cause order creation to fail.

Validation Response

{
  "success": true,
  "data": {
    "valid": true,
    "canSubmit": true,
    "errors": [],
    "warnings": [
      {
        "field": "shippingAddress.state",
        "code": "FORMAT_WARNING",
        "message": "US state should be 2-letter code (e.g., TX, CA)",
        "value": "Texas"
      }
    ],
    "resolvedOrder": {
      "externalOrderId": "ORD-12345",
      "items": [
        {
          "originalSku": "MY-CBD-1000",
          "platformSku": "CBD-OIL-1000-FS",
          "platformProductId": "prod_def456",
          "productName": "Wellness CBD 1000mg",
          "quantity": 2,
          "unitPrice": 59.99,
          "effectivePrice": 59.99,
          "isPrivateLabel": true,
          "available": true,
          "availableQty": 150
        }
      ],
      "subtotal": "119.98",
      "shippingCost": "9.99",
      "taxAmount": "0.00",
      "discount": "0.00",
      "total": "129.97"
    },
    "summary": {
      "errorCount": 0,
      "warningCount": 1,
      "itemsResolved": 1,
      "itemsTotal": 1
    }
  }
}

Required Fields Reference

Order Required Fields

Field	Type	Description
externalOrderId	string	Your unique order identifier
items[].sku	string	Product SKU (your SKU or platform SKU)
items[].quantity	number	Quantity to order (minimum 1)
customer.email	string	Customer email for notifications
customer.firstName	string	Customer first name
customer.lastName	string	Customer last name
shippingAddress.line1	string	Street address
shippingAddress.city	string	City name
shippingAddress.state	string	State/province (2-letter code for US)
shippingAddress.postalCode	string	ZIP/postal code
shippingAddress.country	string	ISO country code (US, CA, etc.)

Best Practices

Use Consistent SKU Formats

Define a consistent SKU format for your products (e.g., BRAND-PRODUCT-SIZE). This makes bulk imports easier and reduces mapping errors.

Always Validate in Development

Call the /orders/validate endpoint during development to catch mapping issues before they affect real orders.

Use Price Overrides Wisely

Price overrides on SKU mappings let you set custom prices per product. Use these for negotiated pricing or promotional rates.

Monitor Validation Logs

Failed validations are logged for debugging. Review these logs in the dashboard to identify recurring issues.