Skip to content
snapcasterDevelopers

Golden path

This is the continuous end-to-end walk for the Partner sandbox. Every request uses https://api-sandbox.snapcaster.ca/api/v1/marketplace, and every authenticated request uses the provisioned Seller’s Marketplace API key. The requests and responses below are composed from the curated examples in the committed OpenAPI contract.

Before starting, obtain the sandbox API key, the known-good Catalog skuId and productId, and the per-Platform sandbox Signing secret. Register a sandbox webhook receiver for webhook testing.

Step 1: verify your credential

Start by proving that the provisioned Seller credential reaches the expected store.

Request

Step 1 cURL request - Sandbox
curl --request GET \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/me' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY"

Expected observation

A 200 response identifies the sandbox store, reports CAD, active true, vacation false, and the current Listing counts.

Step 1 curated response
{
  "success": true,
  "data": {
    "sellerCode": "sandbox-cards",
    "storeName": "Sandbox Cards",
    "currency": "CAD",
    "region": "CA",
    "active": true,
    "vacation": false,
    "counts": {
      "total": 1,
      "matched": 1,
      "unmatched": 0,
      "browsable": 1
    },
    "readiness": {
      "browseEligible": true,
      "effectiveTermsVersion": "2026-07",
      "incompletePrerequisites": []
    }
  }
}

Most likely failure

401 UNAUTHORIZED means the Marketplace API key was mistyped, truncated, or revoked, so re-copy the complete Seller-scoped key because there is no platform-level inbound credential.

Step 2: push a first Listing

The request body comes directly from the operation’s curated example and uses integer cents for price.

Request

Step 2 cURL request - Sandbox
curl --request POST \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/listings' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "skuId": 427286,
  "productId": 24692,
  "price": 2499,
  "quantity": 3,
  "externalRef": "platform-listing-1042",
  "asOf": "2026-09-04T18:30:00.000Z"
}'

Expected observation

The per-item result is applied, and a follow-up GET /me reports one total and one matched Listing.

Step 2 curated response
{
  "success": true,
  "data": {
    "results": [
      {
        "skuId": 427286,
        "op": "upsert",
        "status": "applied",
        "externalRef": "platform-listing-1042"
      }
    ]
  }
}

Most likely failure

An unmatched result means the skuId did not resolve to the Canonical Catalog, so use the known-good pair sent with the sandbox; a rejected result instead names the request field to correct.

Step 3: confirm it is browsable

Poll GET /me until counts.browsable reaches one, then inspect the public Product as a Buyer would. This Browse request is informational and unauthenticated; a Platform does not implement the endpoint.

Request

Step 3 cURL request - Sandbox
curl --request GET \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/products/24692'

Expected observation

The public Product response includes the sandbox store in offers with the pushed price and Available quantity, with the buyer-facing price rendered in display units.

Step 3 curated response
{
  "success": true,
  "data": {
    "offers": [
      {
        "lane": "native",
        "productId": 24692,
        "sellerId": 42,
        "storeSlug": null,
        "variantId": null,
        "skuId": 427286,
        "sellerName": "Sandbox Cards",
        "condition": "Near Mint",
        "language": "English",
        "finish": "Non-Foil",
        "isSealed": false,
        "price": 2499,
        "available": 3,
        "checkoutMode": "express",
        "salesCount": 18,
        "sellerCode": "sandbox-cards",
        "reviewScore": {
          "score": 4.93,
          "count": 15
        },
        "poBoxDelivery": {
          "status": "available"
        },
        "disclosures": {
          "imageSource": "catalog",
          "conditionSource": "seller_declared",
          "authenticitySource": "seller_attestation",
          "snapcasterInspected": false,
          "snapcasterGraded": false,
          "snapcasterAuthenticated": false,
          "gradingStandard": "snapcaster-magic-v1",
          "declaredGrade": "Near Mint",
          "buyerProtection": "magic-grade-and-authenticity"
        },
        "fulfillmentObligation": {
          "sku": "exact",
          "printing": "exact",
          "language": "exact",
          "finish": "exact",
          "condition": "declared-or-better"
        }
      }
    ],
    "product": {
      "productId": 24692,
      "name": "Lightning Bolt",
      "set": "Magic 2011",
      "rarity": "Uncommon",
      "collectorNumber": "149",
      "imageUrl": "https://images.snapcaster.ca/catalog/24692.jpg",
      "details": [
        {
          "label": "Card Type",
          "value": "Instant"
        },
        {
          "label": "Mana Cost",
          "value": "{R}"
        }
      ]
    }
  }
}

Most likely failure

If matched is one but browsable stays zero, read the incomplete prerequisites returned by GET /me, where Shipping, payout readiness, current Terms, tax, Canadian origin, native Checkout, and authenticator enrollment are the common sandbox gates.

Step 4: receive a test Order

Email support after the offer is browsable so Snapcaster can run a Stripe test-mode purchase. Observe the Order through the signed order.created Delivery, this poll, or both.

Request

Step 4 cURL request - Sandbox
curl --request GET \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/orders?since=2026-09-04T18%3A00%3A00.000Z' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY"

Expected observation

The poll returns the scripted Order with the pushed skuId, echoed external_ref, Customer, integer-cent money, Shipping, and API version in the same byte shape as order.created data.

Step 4 curated response
{
  "success": true,
  "data": {
    "items": [
      {
        "order_id": "ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW",
        "seller_id": 42,
        "created_at": "2026-09-04T18:42:17.000Z",
        "currency": "CAD",
        "customer": {
          "name": "Alex Morgan",
          "email": "alex.morgan@example.test",
          "shipping_address": {
            "line1": "123 Sandbox Avenue",
            "line2": "Unit 4",
            "city": "Toronto",
            "province": "ON",
            "postal_code": "M5V 2T6",
            "country": "CA"
          }
        },
        "lines": [
          {
            "sku_id": 427286,
            "product_id": 24692,
            "quantity": 1,
            "unit_price": 2499,
            "name": "Lightning Bolt",
            "set": "Magic 2011",
            "condition": "Near Mint",
            "external_ref": "platform-listing-1042",
            "language": "English",
            "finish": "Non-Foil"
          }
        ],
        "totals": {
          "subtotal": 2499,
          "shipping": 599,
          "tax": 403,
          "grand_total": 3501
        },
        "tax": {
          "lines": [
            {
              "label": "HST",
              "rate": 0.13,
              "amount": 403
            }
          ]
        },
        "shipping": {
          "method": "Tracked parcel",
          "cost": 599
        },
        "buyer_notes": "Please protect the card with a top loader."
      }
    ],
    "nextCursor": null
  }
}

Most likely failure

If the poll is empty, confirm that support ran the scripted purchase after the Listing became browsable and that since precedes the purchase, while remembering that a missing webhook does not block this poll.

Step 5: report Fulfillment

Progress the Order to shipped with the curated Tracking example.

Request

Step 5 cURL request - Sandbox
curl --request PATCH \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/orders/ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW/fulfillment' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "status": "shipped",
  "trackingCompany": "Canada Post",
  "trackingNumber": "CX123456789CA",
  "trackingUrl": "https://www.canadapost-postescanada.ca/track-reperage/en#/details/CX123456789CA"
}'

Expected observation

The response is the post-transition Order at shipped with the submitted Tracking, and GET /orders/{orderId} reads the same state.

Step 5 curated response
{
  "success": true,
  "data": {
    "order_id": "ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW",
    "seller_id": 42,
    "created_at": "2026-09-04T18:42:17.000Z",
    "currency": "CAD",
    "customer": {
      "name": "Alex Morgan",
      "email": "alex.morgan@example.test",
      "shipping_address": {
        "line1": "123 Sandbox Avenue",
        "line2": "Unit 4",
        "city": "Toronto",
        "province": "ON",
        "postal_code": "M5V 2T6",
        "country": "CA"
      }
    },
    "lines": [
      {
        "sku_id": 427286,
        "product_id": 24692,
        "quantity": 1,
        "unit_price": 2499,
        "name": "Lightning Bolt",
        "set": "Magic 2011",
        "condition": "Near Mint",
        "external_ref": "platform-listing-1042",
        "language": "English",
        "finish": "Non-Foil"
      }
    ],
    "totals": {
      "subtotal": 2499,
      "shipping": 599,
      "tax": 403,
      "grand_total": 3501
    },
    "tax": {
      "lines": [
        {
          "label": "HST",
          "rate": 0.13,
          "amount": 403
        }
      ]
    },
    "shipping": {
      "method": "Tracked parcel",
      "cost": 599
    },
    "buyer_notes": "Please protect the card with a top loader.",
    "status": "shipped",
    "fulfillment": {
      "tracking_company": "Canada Post",
      "tracking_number": "CX123456789CA",
      "tracking_url": "https://www.canadapost-postescanada.ca/track-reperage/en#/details/CX123456789CA"
    }
  }
}

Most likely failure

422 INVALID_TRANSITION means the lifecycle cannot make that move, often because shipped was retried after succeeding, so read the Order and branch on its current state; a wrong-Seller id is 404 ORDER_NOT_FOUND.

Step 6: observe the payout-ready Order

Re-read the exact Order while the sandbox release sweep runs every five minutes. The expected Transfer is the grand total less the Platform fee, commission tax, and platform-collected tax.

Request

Step 6 cURL request - Sandbox
curl --request GET \
  --url 'https://api-sandbox.snapcaster.ca/api/v1/marketplace/orders/ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW' \
  --header "Authorization: Bearer $MARKETPLACE_API_KEY"

Expected observation

The Order still reads shipped with its frozen totals and Shipping while the zero-hold sandbox transfer sweep moves the eligible test amount to the Seller's Stripe test-mode Connected account.

Step 6 curated response
{
  "success": true,
  "data": {
    "order_id": "ord_sandbox_01K4A8Y6D4QJH2N3P5R7S9T0VW",
    "seller_id": 42,
    "created_at": "2026-09-04T18:42:17.000Z",
    "currency": "CAD",
    "customer": {
      "name": "Alex Morgan",
      "email": "alex.morgan@example.test",
      "shipping_address": {
        "line1": "123 Sandbox Avenue",
        "line2": "Unit 4",
        "city": "Toronto",
        "province": "ON",
        "postal_code": "M5V 2T6",
        "country": "CA"
      }
    },
    "lines": [
      {
        "sku_id": 427286,
        "product_id": 24692,
        "quantity": 1,
        "unit_price": 2499,
        "name": "Lightning Bolt",
        "set": "Magic 2011",
        "condition": "Near Mint",
        "external_ref": "platform-listing-1042",
        "language": "English",
        "finish": "Non-Foil"
      }
    ],
    "totals": {
      "subtotal": 2499,
      "shipping": 599,
      "tax": 403,
      "grand_total": 3501
    },
    "tax": {
      "lines": [
        {
          "label": "HST",
          "rate": 0.13,
          "amount": 403
        }
      ]
    },
    "shipping": {
      "method": "Tracked parcel",
      "cost": 599
    },
    "buyer_notes": "Please protect the card with a top loader."
  }
}

Most likely failure

If no Transfer appears after about ten minutes, confirm the Order is shipped, inspect Stripe test mode rather than live mode, confirm that the Order was not cancelled or refunded, and ask support to verify the Transfer id and amount.

Optional terminations and cleanup

Section titled “Optional terminations and cleanup”

Use a second test Order to exercise pre-ship Cancellation and post-ship Refund. Return the original Listing to quantity zero when finished so persistent sandbox state does not surprise the next test run.

Need help?

Email Marketplace support with this page and the sandbox environment prefilled.

Never include an API key or Signing secret in the message.