Skip to main content
The Zinc API provides a sandbox environment for testing your integration without placing real orders or incurring charges. Test mode uses isolated data and simulates various order scenarios.

​
Enabling Test Mode

There are two ways to enable test mode:

​
Option 1: Test API Key

Use an API key with the zn_test_ prefix: 
curl https://api.zinc.com/orders \
  -H "Authorization: Bearer zn_test_abc123..."

​
Option 2: X-Test-Mode Header

Add the X-Test-Mode: true header to any request: 
curl https://api.zinc.com/orders \
  -H "Authorization: Bearer zn_live_abc123..." \
  -H "X-Test-Mode: true"
Test mode uses a separate sandbox database. Orders created in test mode are completely isolated from production data.

​
Test Products

Use these special product URLs to simulate different order scenarios:
Product URLScenarioDescription
https://zinc.com/shop/products/test-successSuccessOrder completes successfully
https://zinc.com/shop/products/test-out-of-stockOut of StockProduct is unavailable
https://zinc.com/shop/products/test-price-exceededPrice ExceededTotal exceeds max_price
https://zinc.com/shop/products/test-invalid-addressInvalid AddressShipping address validation fails
https://zinc.com/shop/products/test-url-unreachableURL UnreachableProduct URL is inaccessible
https://zinc.com/shop/products/test-invalid-variantInvalid VariantVariant selection required
https://zinc.com/shop/products/test-shipping-unavailableShipping UnavailableCannot ship to address
https://zinc.com/shop/products/test-insufficient-fundsInsufficient FundsWallet balance too low

​
Get Test Products Programmatically

curl https://api.zinc.com/orders/test-products \
  -H "Authorization: Bearer <your_api_key>"

​
Response

{
  "products": [
    {
      "url": "https://zinc.com/shop/products/test-success",
      "scenario": "success",
      "name": "Success",
      "is_synchronous_error": false
    },
    {
      "url": "https://zinc.com/shop/products/test-invalid-address",
      "scenario": "invalid_address",
      "name": "Invalid Address",
      "is_synchronous_error": true
    }
  ]
}

​
Error Timing

Test scenarios produce errors at different stages:

​
Synchronous Errors

These errors occur immediately when creating the order:
  • test-invalid-address - Returns invalid_shipping_address error
  • test-url-unreachable - Returns url_unreachable error
  • test-insufficient-funds - Returns insufficient_funds error

​
Example

curl -X POST https://api.zinc.com/orders \
  -H "Authorization: Bearer zn_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{"url": "https://zinc.com/shop/products/test-invalid-address"}],
    "shipping_address": {...},
    "max_price": 5000
  }'

{
  "code": "invalid_shipping_address",
  "message": "The shipping address failed validation (test scenario)"
}

​
Asynchronous Errors

These errors occur during order processing and are delivered via webhooks:
  • test-out-of-stock - Order fails with product_out_of_stock
  • test-price-exceeded - Order fails with max_price_exceeded
  • test-invalid-variant - Order fails with invalid_variant
  • test-shipping-unavailable - Order fails with shipping_unavailable
The order is created successfully, but transitions to failed status during processing.

​
Test Success Scenario

The test-success product simulates a complete successful order: 
curl -X POST https://api.zinc.com/orders \
  -H "Authorization: Bearer zn_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "products": [{"url": "https://zinc.com/shop/products/test-success"}],
    "shipping_address": {
      "name": "John Smith",
      "address_line_1": "123 Main Street",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US",
      "phone": "206-555-0100"
    },
    "max_price": 5000
  }'

​
Successful Test Order Response

When retrieved after processing: 
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "order_placed",
  "merchant_order_id": "TEST-550e8400",
  "tracking_numbers": [
    {
      "carrier": "usps",
      "tracking_number": "ZINC_TEST_123456789"
    }
  ],
  "price_components": {
    "subtotal": 4500,
    "tax": 250,
    "shipping": 150,
    "total": 4900
  }
}

​
Skipped Validations

In test mode, the following validations are bypassed to simplify testing:
  • Wallet balance checks
  • US retailer URL validation
  • URL reachability validation
  • Shipping address country validation
  • Address verification via external APIs
Test mode behavior differs from production. Always perform final testing with real orders before going live.

​
Data Isolation

Test mode data is completely isolated:
  • Orders created in test mode are stored in a sandbox database
  • Test orders do not appear in production order lists
  • Production orders do not appear in test mode
  • Wallet balances are separate between test and production

​
Best Practices

  1. Start with test mode - Build and test your entire integration using test products before switching to production
  2. Test all scenarios - Use each test product to verify your error handling works correctly
  3. Test webhooks - Configure webhooks and verify you receive events for both successful and failed test orders
  4. Verify error handling - Ensure your application gracefully handles both synchronous and asynchronous errors
  5. Use consistent mode - Don’t mix test and production API keys in the same environment