snapcasterDevelopers

    API reference · Sandbox

    Read a sandbox test purchase

    GET /sandbox/test-purchases/{ref}

    Sandbox only: the production API does not serve this operation. Read a test purchase this seller started: processing until its order exists, then succeeded with the order_ids, or failed with the reason.

    Example

    These examples send requests to the sandbox.

    Replace the example ref in the URL with your own.

    Generated cURL request - Sandbox
    curl --request GET \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/sandbox/test-purchases/string' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY"
    Response 200: Order created
    {
  "success": true,
  "data": {
    "test_purchase_ref": "tpr_3f2c0b9d8e7a6f5c4b3a29180f7e6d5c",
    "checkout_id": "chk_4e1f7a2b9c3d",
    "status": "succeeded",
    "order_ids": [
      "ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW"
    ],
    "failure": null
  }
}

    Endpoint

    EnvironmentURL
    Sandboxhttps://api-sandbox.snapcaster.ca/api/v1/marketplace/sandbox/test-purchases/{ref}
    Authentication
    • marketplaceApiKey - http bearer. Send the seller's marketplace API key as Authorization: Bearer mp_{sellerCode}_{hex}. The mp_{sellerCode}_ prefix identifies the seller; the trailing hex is the secret. The seller generates the key and supplies it to your platform.

    Request

    Path parameters

    ref string required

    The test_purchase_ref the trigger returned.

    Constraints: minimum length: 1; maximum length: 64

    Headers

    X-Snapcaster-Api-Version string

    Override the platform pin for this request only. Webhook versions and the platform pin do not change.

    Constraints: allowed values: 2026-10 Example 2026-10

    Response

    200

    The test purchase.

    Response body: SandboxTestPurchaseResponse

    success boolean required

    Whether the operation completed as requested.

    Constraints: allowed values: true Example true

    data SandboxTestPurchase required

    The operation or event payload.

    Show child fieldsHide child fields
    data.test_purchase_ref string required

    Stable for the Idempotency-Key that started the purchase.

    Example tpr_3f2c0b9d8e7a6f5c4b3a29180f7e6d5c

    data.checkout_id string required

    The checkout the sandbox buyer paid through.

    Example chk_4e1f7a2b9c3d

    data.status string required

    processing until the payment is captured and the order exists, then succeeded. failed when the payment did not complete.

    Constraints: allowed values: processing, succeeded, failed Example succeeded

    data.order_ids array of string required

    The orders the purchase created, as order_id values. Empty until succeeded.

    Field example[ "ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW" ]
    data.failure object or null required

    Why the purchase failed, or null.

    Show child fieldsHide child fields
    data.failure.code string required

    The stable machine-readable code for this result.

    Constraints: allowed values: TEST_PAYMENT_FAILED, TEST_PURCHASE_NOT_AVAILABLE

    data.failure.message string required

    A human-readable explanation of the result.

    Errors

    Errors return a MarketplaceError body, except HTTP 500 (ApiError). Error codes explains both error bodies and lists every code.

    • 400 UNSUPPORTED_API_VERSION

      Unknown or retired API-version override (UNSUPPORTED_API_VERSION).

      Do this: For UNSUPPORTED_API_VERSION, choose a supported version from the API versioning guide.

    • 401 UNAUTHORIZED

      Missing or invalid marketplace API key (UNAUTHORIZED).

      Do this: Send the marketplace API key for this seller as a Bearer token, then retry.

    • 404 TEST_PURCHASE_NOT_FOUND

      No test purchase matches this ref for the authenticated seller (TEST_PURCHASE_NOT_FOUND). Another seller's ref also returns 404.

      Do this: Use the test_purchase_ref the trigger returned to this seller.

    • 500 INTERNAL_ERROR

      An unexpected failure (INTERNAL_ERROR).

      Do this: Retry with bounded retries and jitter. If the failure persists, contact Snapcaster with the X-Correlation-ID response header.

    Changelog

    None.