Skip to main content
Vinaway
Shop Now

Vinaway API Documentation

Integrate your e-commerce store with Vinaway's fulfillment network. Automate order processing, track shipments, and manage products directly from your application.

Introduction

The Vinaway API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Production: https://api.vinaway.io/api

Development: https://dev.api.vinaway.io/api

Authentication

Authenticate your API requests using a Bearer token. To obtain a token, you need to exchange your email and password.

POST /token

Request Body

{
    "email": "your_email@example.com",
    "password": "your_password"
}

Response

{
    "access_token": "76|5lrXZKyBRTRL8pDvpUBNZ...",
    "token_type": "Bearer",
    "expires_in": 18000
}

Create Order

Create a new production order. This endpoint accepts a list of items to be fulfilled.

POST /orders

Parameters

Field Type Required Description
type integer Yes Order type (1: Production, 2: Dropship, 3: Design)
external_order_id string No Your unique identifier for this order
production_line_id integer Yes ID of the production line (e.g., 1 for Standard)
customer_name string Yes Name of the customer
items array Yes Array of items to produce

Example Request

{
    "type": 1,
    "external_order_id": "ORD-2024-001",
    "production_line_id": 1,
    "customer_name": "John Doe",
    "address1": "123 Main St",
    "city": "New York",
    "zip": "10001",
    "country": "US",
    "state": "NY",
    "items": [
        {
            "product_id": 1,
            "product_sku_id": 1,
            "quantity": 1,
            "mockup1": "https://example.com/mockup-front.png",
            "productSurfaces": [
                {
                    "product_surface_id": 3,
                    "design_png": "https://example.com/design.png"
                }
            ]
        }
    ]
}

Success Response

{
    "success": true,
    "message": "Seller Order Created Successfully.",
    "id": 313,
    "internal_order_id": "VN7PIEA4FA5U"
}

Get Order

Retrieve details of a specific order by its internal ID.

GET /orders/{internal_order_id}

Example Request

GET https://api.vinaway.io/api/orders/VN7PIEA4FA5U

Response

{
    "internal_order_id": "VN7PIEA4FA5U",
    "status": 0,
    "amount_total": 2470,
    "customer_name": "John Doe",
    "line_items": [
        {
            "product": {
                "name": "Unisex T-Shirt"
            },
            "quantity": 1
        }
    ]
}

List Orders

Retrieve a paginated list of your orders.

GET /orders

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
limit integer Number of items per page (default: 15)

Webhooks

Vinaway can send HTTP POST notifications to a URL you configure when certain events happen in your account. This allows your application to react in real-time without polling our API.

Configuration

Contact your Vinaway account manager to configure your webhook URL. Once configured, Vinaway will begin sending POST requests to that URL for the events described below.

Request Format

Method: POST

Content-Type: application/json

All webhook payloads follow this structure: 

{
    "event": "order_processed",
    "data": { ... }
}

Verifying Signatures

Each webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 hex digest of the request body. Verify it to ensure the webhook came from Vinaway: 

$secret = "your_shared_secret";  // Provided by Vinaway for your account
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $body, $secret);
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

Retry Policy

Vinaway expects a 2XX response within 10 seconds. If your endpoint returns a non-2XX status or times out, the webhook is NOT automatically retried. Please ensure your endpoint is reliable.

Webhook: Order Processed

Sent when an order finishes production and moves to "Waiting for Packaging" status. The payload contains the full order detail, identical to the GET /orders/{id} response.

Payload

{
    "event": "order_processed",
    "data": {
        "id": 313,
        "internal_order_id": "VN7PIEA4FA5U",
        "external_order_id": "ORD-2024-001",
        "type": 1,
        "status": 6,
        "is_paid": 1,
        "amount_subtotal": 2000,
        "amount_shipping": 470,
        "amount_total": 2470,
        "customer_name": "John Doe",
        "address1": "123 Main St",
        "city": "New York",
        "state_name": "NY",
        "country_name": "United States",
        "zip": "10001",
        "tracking_number": null,
        "tracking_carrier": null,
        "seller": {
            "id": 42,
            "name": "Example Store"
        },
        "seller_order_skus": [
            {
                "id": 501,
                "quantity": 1,
                "price": 2000,
                "product": {
                    "id": 1,
                    "name": "Unisex T-Shirt"
                },
                "seller_order_sku_designs": [...]
            }
        ],
        "production_line": {
            "id": 1,
            "name": "Standard"
        },
        "created_at": "2026-08-01 14:30:00"
    }
}

Order Status Reference

Status Code Name Description
-1Shipping Cost ProcessingOrder placed, calculating shipping
0PendingAwaiting processing
1Ordering DesignDesign being ordered
2Waiting for Design ConfirmationDesign awaiting seller confirmation
3Waiting for ProductionDesign confirmed, queued for production
4Approved for ProductionApproved by factory
5In ProductionCurrently being manufactured
6Waiting for PackagingWebhook trigger — production complete
7ShippedPackage handed to carrier
8CompletedDelivered / fulfillment complete
9RefundedOrder refunded
99CanceledOrder canceled

Production Lines

Get a list of available production lines to use when creating an order.

GET /production-lines

Response

{
    "total": 2,
    "data": [
        {
            "id": 1,
            "name": "Standard",
            "description": "Inproduction: 1-3 days\nShip : 3-7days",
            "level": 1
        },
        {
            "id": 2,
            "name": "Express",
            "description": "Inproduction 4h\nShip 1-3 days",
            "level": 2
        }
    ]
}

Products

Get a list of all products.

GET /products

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
limit integer Number of items per page (default: 100)

Response

{
    "total": 50,
    "data": [
        {
            "id": 1,
            "name": "Classic T-Shirt",
            "sku": "TSHIRT-001"
        }
    ]
}

Variants

Get a list of all product variants (SKUs). Use these IDs when creating orders.

GET /product-skus

Query Parameters

Parameter Type Description
page integer Page number (default: 1)
limit integer Number of items per page (default: 100)

Response

{
    "total": 120,
    "data": [
        {
            "id": 101,
            "sku": "TSHIRT-BLK-S",
            "product_name": "Classic T-Shirt",
            "color": "Black",
            "size": "S"
        }
    ]
}