Sandbox & Testing

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

Use an API key with the zn_test_ prefix:

curl https://api.zinc.com/orders \
  -H "Authorization: Bearer zn_test_abc123..."

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 URL	Scenario	Description
`https://zinc.com/shop/products/test-success`	Success	Order completes successfully
`https://zinc.com/shop/products/test-out-of-stock`	Out of Stock	Product is unavailable
`https://zinc.com/shop/products/test-price-exceeded`	Price Exceeded	Total exceeds `max_price`
`https://zinc.com/shop/products/test-invalid-address`	Invalid Address	Shipping address validation fails
`https://zinc.com/shop/products/test-url-unreachable`	URL Unreachable	Product URL is inaccessible
`https://zinc.com/shop/products/test-invalid-variant`	Invalid Variant	Variant selection required
`https://zinc.com/shop/products/test-shipping-unavailable`	Shipping Unavailable	Cannot ship to address
`https://zinc.com/shop/products/test-insufficient-funds`	Insufficient Funds	Wallet balance too low

Get Test Products Programmatically

You can also retrieve the full list of test products from the API:

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

Example 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": {
      "first_name": "John",
      "last_name": "Smith",
      "address_line1": "123 Main Street",
      "city": "Seattle",
      "state": "WA",
      "postal_code": "98101",
      "country": "US",
      "phone_number": "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

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

Getting Started

Search (Beta)

Orders

Bulk Orders

Managed Accounts

Returns

Product Data

Retailers

Agent

Usage

Enabling Test Mode

Test Products

Get Test Products Programmatically

Example Response

Error Timing

Synchronous Errors

Example

Asynchronous Errors

Test Success Scenario

Successful Test Order Response

Skipped Validations

Data Isolation

Best Practices

​Enabling Test Mode

​Test Products

​Get Test Products Programmatically

​Example Response

​Error Timing

​Synchronous Errors

​Example

​Asynchronous Errors

​Test Success Scenario

​Successful Test Order Response

​Skipped Validations

​Data Isolation

​Best Practices

Enabling Test Mode

Test Products

Get Test Products Programmatically

Example Response

Error Timing

Synchronous Errors

Example

Asynchronous Errors

Test Success Scenario

Successful Test Order Response

Skipped Validations

Data Isolation

Best Practices