Shopify Draft Order API

A small Node.js Express API for creating Shopify customers, orders, and draft orders from a single request.

Overview

This repository contains a simple API server built with Express. It includes:

• POST /api/create-order to create a Shopify order
• POST /api/create-draft-order to create a Shopify draft order
• Customer lookup and creation by email
• Request validation for required fields
• Logging to console and logs/app.log
• Security middleware, rate limiting, CORS, and request logging

What is in the code

• server.js: main application file
  • loads environment variables with dotenv
  • configures Express with helmet, cors, morgan, and express-rate-limit
  • validates required environment variables: SHOPIFY_STORE and SHOPIFY_ACCESS_TOKEN
  • defines helper functions for Shopify requests and request body validation
  • creates or finds a Shopify customer before creating an order or draft order
  • writes logs to logs/app.log
• package.json: project configuration and dependencies
• logs/: automatically created directory for log output

Setup

1. Install dependencies:

npm install

2. Create a .env file in the project root with the following values:

SHOPIFY_STORE=your-store.myshopify.com
SHOPIFY_ACCESS_TOKEN=shpat_xxxxxxxxxxxxxxxx
PORT=3000

3. Start the server:

npm start

4. Open your browser or API client to:

http://localhost:3000/

Environment variables

Required values:

• SHOPIFY_STORE: your Shopify store domain, for example your-store.myshopify.com
• SHOPIFY_ACCESS_TOKEN: your store access token
• PORT: optional. Defaults to 3000 if not set

Security & Rate Limiting

The API includes the following security features:

• Helmet.js — sets security HTTP headers
• CORS — allows requests from any origin (configurable)
• Rate Limiting — limits requests to 100 per 15 minutes per IP
• Request Validation — validates all required fields before processing
• Timeout Protection — 15 second timeout on all Shopify API requests
• Global Error Handler — catches and logs unhandled errors

Logging

The API logs all activity to both console and logs/app.log:

• Request details (endpoint, method)
• Customer operations (creation, lookup)
• Order/Draft order creation (success/failure)
• Validation errors
• Shopify API responses
• Unhandled exceptions

Each log entry includes:

• Timestamp (ISO format)
• Log type (REQUEST, CUSTOMER, ORDER_SUCCESS, etc.)
• Message
• Associated data (as JSON)

How the API works

The server exposes these endpoints:

• GET / — health check
• POST /api/create-order — create a Shopify order
• POST /api/create-draft-order — create a Shopify draft order

For both POST endpoints, the API will:

1. validate request fields (name, variant_id are required)
2. optionally find or create a Shopify customer by email
3. build order or draft order line item properties (name, phone, email, reference file)
4. add tags: custom-design and api-order (or draft-order)
5. set financial status to pending for orders
6. send a request to Shopify using the configured store and access token
7. log request and result details to logs/app.log and console

Customer Handling

• If an email is provided, the API searches for an existing customer
• If found, the existing customer is attached to the order
• If not found, a new customer is created with tags: api-customer
• If no email is provided, the order is created without a customer

Data to send to the API

Send JSON data in the request body. The API expects the following fields:

• name (string) — required, used for customer first name and line item properties
• email (string) — optional, but used to search/create a customer. Must be valid email format.
• phone (string) — optional; if provided, must use international format like +919999999999 or +1234567890. Phone is included in billing/shipping address for visibility in Shopify dashboard.
• variant_id (number or string convertible to number) — required, the Shopify product variant ID
• quantity (number) — optional, defaults to 1 when missing or invalid
• reference_file (string) — optional custom value stored in line item properties (e.g., design file name)

Example request body

{
  "name": "John Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "variant_id": 1234567890,
  "quantity": 2,
  "reference_file": "design-xyz.pdf"
}

Notes on field behavior

• name must be a string and is required.
• variant_id must be a valid number and is required.
• quantity must be greater than 0 if provided; otherwise the API defaults to 1.
• email is validated for format if included. It must contain @ and a domain.
• phone is optional, but must be in international format if provided (e.g., +1234567890).
• reference_file is stored in line item properties as a custom field.
• When email is provided but invalid, the request fails validation.
• When email is valid but no customer exists, a new customer is created.
• All orders are tagged with custom-design and api-order (or draft-order for draft orders).
• Orders have financial_status set to pending.

Example requests

Create order

POST /api/create-order

Response on success (HTTP 200):

{
  "success": true,
  "message": "Order created successfully",
  "customer_id": 123456789,
  "order_id": 987654321,
  "order_name": "#1001",
  "order_number": 1001,
  "created_at": "2026-05-13T00:00:00Z"
}

Response on validation error (HTTP 400):

{
  "success": false,
  "message": "Valid name is required"
}

Create draft order

POST /api/create-draft-order

Response on success (HTTP 200):

{
  "success": true,
  "message": "Draft order created successfully",
  "customer_id": 123456789,
  "draft_order_id": 987654321,
  "invoice_url": "https://your-store.myshopify.com/123456789/draft_orders/987654321/invoice",
  "order_name": "#1001",
  "status": "open",
  "created_at": "2026-05-13T00:00:00Z"
}

HTTP Status Codes

• 200 OK — request successful, order/draft order created
• 400 Bad Request — validation error (missing or invalid fields)
• 429 Too Many Requests — rate limit exceeded (max 100 requests per 15 minutes)
• 500 Internal Server Error — server or Shopify API error

Common Error Messages

• "Valid name is required" — name field is missing or not a string
• "Valid variant ID is required" — variant_id is missing or not a number
• "Invalid email format" — email provided but doesn't match email pattern
• "Quantity must be greater than 0" — quantity is less than or equal to 0
• "Order creation failed" — Shopify API returned an error
• "Too many requests" — rate limit exceeded

Notes and recommendations

• The code uses Shopify API version 2026-04
• Rate Limiting — The app blocks more than 100 requests per 15 minutes from the same IP
• Request Timeout — All Shopify API requests have a 15-second timeout to prevent hanging
• Customer Creation — createCustomer logic only runs when email is present in the request
• Error Responses — Failed Shopify API calls include the shopify_response data for debugging
• Tags — All customers are tagged with api-customer. Orders are tagged with custom-design and api-order or draft-order
• Billing/Shipping Address — Both include name and phone for visibility in Shopify dashboard
• Line Item Properties — Custom properties are stored for tracking (name, phone, email, reference file)
• Logs Directory — Automatically created if it doesn't exist; old logs are appended to logs/app.log

Troubleshooting

Missing environment variables error

Problem: "❌ Missing environment variables"

Solution: Ensure your .env file contains both SHOPIFY_STORE and SHOPIFY_ACCESS_TOKEN.

Order creation fails with Shopify error

Problem: "Order creation failed" with shopify_response error

Solution: Check that:

• The variant_id exists in your Shopify store
• The SHOPIFY_ACCESS_TOKEN has permission to create orders
• The SHOPIFY_STORE domain is correct
• Check the logs in logs/app.log for the full Shopify API error

Rate limit exceeded

Problem: "Too many requests" (HTTP 429)

Solution: Wait 15 minutes before making more requests from the same IP, or use a different IP address.

Phone number issues

Problem: Phone doesn't appear in Shopify order

Solution: Ensure phone is in international format (e.g., +12125551234 or +919999999999).

Customer not found when creating subsequent orders

Problem: New customer created instead of finding existing customer

Solution: This is expected if the email in the request doesn't exactly match an existing customer email in your Shopify store.

Author

• Name: Dhruv Akbari
• Email: dhruvakbari303@gmail.com

Replace the author name and email above with your actual details.