SexToy Wholesale Order Management API Documentation

Introduction

Welcome to the SexToy Wholesale Order Management API. This API provides a secure and efficient way for our partners to automate order processing, including creating and managing orders. Our API is designed to streamline operations for bulk purchasing, making it easier for you to integrate our platform directly into your internal systems.

Authentication

All API requests require the use of an API key for authentication. The API key should be included in the request header as

X-API-KEY: <Your-API-Key>

Base URL

All API requests should be made to the base URL:

https://api.cnv.com

Please ensure that you use this base URL for all your requests to the SexToy Wholesale Order Management API.

Create an Order

Creates a new order with detailed shipping information, line items, and more.

Request URL

POST https://api.cnv.com/orders

Request Body Example

{
  "order": {
    "shippingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "companyName" : "ACE Auto",
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "Anytown",
      "province": "Texas",
      "country": "US",
      "zip": "12345",
      "phoneNumber": "555-888-3232"
    },
    "lineItems": [
      {
        "upc": "685634102308",
        "quantity": 1
      }
    ],
    "shippingMethod": "Standard",
    "internalReferenceNumber": "5333444333334"
  }
}

Response Example

{
  "status": "success",
  "message": "Order created successfully",
  "data": {
    "order_id": "67890",
    "status": "created",
    "created_at": "2024-03-06T12:00:00Z",
    "shippingAddress": {
      "firstName": "John",
      "lastName": "Doe",
      "companyName" : "ACE Auto",
      "address1": "123 Main St",
      "address2": "Apt 4B",
      "city": "Anytown",
      "province": "Texas",
      "country": "US",
      "zip": "12345",
      "phoneNumber": "555-888-3232"
    },
    "lineItems": [
      {
        "upc": "685634102308",
        "quantity": 1
      }
    ],
    "shippingMethod": "Standard",
    "internalReferenceNumber": "5333444333334"
  }
}

Delete an Order

Deletes an existing order by its unique order Reference Number that you provided when creating the order.

Request URL

DELETE https://api.cnv.com/orders/{your_reference_number}

cURL Example

curl -X DELETE "https://api.cnv.com/orders/67890" \
      -H "X-API-KEY: <Your-API-Key>"

Response Example

{
  "message": "Order deleted successfully."
}

Order Status

The Order Status endpoint provides detailed information about an order, including its current status, shipment details, the tracking company responsible for the shipment.

Request URL

GET /orders/status/{your-reference-number}

cURL Example

curl -X GET "https://api.cnv.com//orders/status/67890" \
      -H "X-API-KEY: <Your-API-Key>"

Response Example

{
    "status": "shipped",
    "customer_reference_number": "123456789",
    "submitted_timestamp": "2024-01-01T12:00:00Z",
    "shipment_details": [
        {
            "tracking_number": "TRACK123456",
            "tracking_company": "FastShip Co.",
            "shipped_items": [
                {
                    "sku": "PROD001",
                    "quantity": 2
                },
                {
                    "sku": "PROD002",
                    "quantity": 1
                }
            ]
        }
    ]
}

Notes

The tracking_company field specifies the company responsible for the shipment. This field may be null if not available at the request time.

Common Response Codes

• 200 OK: Request succeeded.
• 201 Created: A new resource was created successfully.
• 400 Bad Request: The server couldn't process the request due to invalid syntax.
• 401 Unauthorized: Missing or invalid authentication credentials.
• 404 Not Found: The requested resource was not found.
• 500 Internal Server Error: An unexpected error occurred on the server.

Error Handling

When accessing undefined routes, the API returns a standardized JSON error response:

{
  "status": 404,
  "error": true,
  "message": "The resource you are looking for could not be found."
}

For additional support or inquiries, please reach out to wholesale@sextoy.com.

Available Shipping Methods and Pricing

When submitting orders through the API, specify a shipping method based on the destination. Below are the shipping methods for both USA and International destinations, along with their respective pricing.

US Domestic Shipping Methods

US (Alaska, Hawaii, Puerto Rico)

International Shipping Method

Note on Order Processing and Payment

Orders submitted via this API are not automatically processed and shipped upon submission. Completion of payment is required before any order is finalized and dispatched to customers. To facilitate payment for orders placed through the API, please follow these steps:

1. Log into your account on the wholesale platform.
2. Navigate to the Bulk Orders section. This page will display all orders that are currently pending payment.
3. On this page, you can also review and make any necessary changes to your order before proceeding with payment.

This process ensures that all orders are correctly finalized according to your specifications and payment preferences.