# Shopify ERP Connector

## Overview

The Shopify Order Export Service is a ERP connector that automatically creates orders in Shopify stores based on payment events from external systems. This service is designed for shops that want to integrate with the Jay platform and automatically sync orders to their Shopify store.

## Core Functionality

### Order Creation Process

- Receives payment events from external systems (e.g., Stripe)
- Fetches additional transaction details from payment processors (Stripe)
- Maps order data to Shopify format
- Creates orders in Shopify with complete billing/shipping information
- Marks orders as paid automatically


### Supported Features

- **Product Variants**: Maps product SKUs to Shopify variant IDs
- **Customer Information**: Creates orders with billing and shipping addresses
- **Tax Calculation**: Automatic tax calculation (19% MwSt by default)
- **Shipping Costs**: Configurable shipping amounts
- **Order Status**: Orders are automatically marked as "PAID"
- **Transaction Tracking**: Links orders to original payment transaction IDs


## Integration Requirements

### Shopify Store Configuration

Your Shopify store must have:

1. **Admin API Access Token** with the following permissions:
  - `write_orders` - Create and modify orders
  - `read_products` - Access product variants
2. **Product Setup**:
  - Products must be created in Shopify before orders can be placed
  - Product variants must have unique SKUs that match your external system


### Required Configuration Parameters

| Parameter | Type | Required | Description |
|  --- | --- | --- | --- |
| `shopify_shop_name` | String | Yes | Your Shopify shop name (without .myshopify.com) |
| `shopify_access_token` | String | Yes | Admin API access token with required permissions |
| `api_version` | String | No | Shopify API version (defaults to 2025-01) |


### Message Format Requirements

| Field Category | Required | Description |
|  --- | --- | --- |
| **Products** | Yes | Array with SKU, quantity, price information |
| **Customer Data** | Yes | Retrieved automatically from payment processor |
| **Transaction Details** | Yes | Payment processor transaction ID |
| **Shipping Costs** | No | Optional shipping costs via custom fields |


## Technical Specifications

### API Version

- Uses Shopify Admin API version **2025-01**
- GraphQL-based API communication


### Order Structure

Created orders include:

- Line items with correct variant IDs and pricing
- Customer billing/shipping addresses
- Tax lines (configurable rate)
- Transaction records marking payment as complete
- Order notes with transaction tracking information
- Tags for order classification


As the simplified checkout only fetches one address, the CSV file may return the same address for both the invoice and the shipping address.

### Error Handling

- Invalid product SKUs result in order creation failure
- Network errors are logged and reported
- Failed orders are stored for debugging


## Shop Owner Benefits

1. **Automated Order Flow**: No manual order entry required
2. **Complete Order Data**: Full customer and transaction information
3. **Inventory Sync**: Leverages Shopify's inventory management
4. **Payment Tracking**: Clear link between payments and orders
5. **Tax Compliance**: Automatic tax calculation and reporting


## Prerequisites for Integration

1. **Shopify Plus or Advanced Plan** (for API access)
2. **Product Catalog Setup** in Shopify with proper SKUs
3. **Admin API Access Token** with required permissions
4. **Jay Platform Integration** for order event processing


## Supported Payment Processors

Currently supports:

- **Stripe**: Full integration with transaction detail fetching
- Extensible architecture for additional processors


## Error Scenarios

The connector handles:

- Invalid product variant IDs
- Missing customer information
- Payment processor API failures
- Shopify API rate limiting
- Network connectivity issues


All errors are logged and failed orders are stored for manual review.

Support
For any questions or support needs during implementation, please contact the [Jay Support Team](mailto:support@transfermedia.de).