Skip to main content

Shopify connector operations

This private integration is in rollout. For collectors and sellers, start with Vault with DYLI for Shopify.

Feature flags​

ServerVariableDefault
Shopify connectorDYLI_SUBMISSIONS_ENABLEDfalse: durable local log only
DYLISHOPIFY_VAULT_SUBMISSIONS_ENABLEDfalse: receiver returns 503 without creating records
BothDYLI_SHOPIFY_BRIDGE_SECRETRequired for live delivery; at least 32 random characters

Keep the bridge secret on the servers, never in a public or NEXT_PUBLIC_ environment variable. Apply migration 202609060001_shopify_vault_submissions.sql before enabling the DYLI receiver. The connector also needs its persistent data volume and Shopify installation credentials.

Enabling the connector delivery flag permits delivery of previously logged, pending paid orders. Review the queue before enabling it. Retries use the same store, order, and reference; do not invent a new reference to retry a failed delivery.

Signed delivery​

POST https://www.dyli.io/api/integrations/shopify/vault

Send Content-Type: application/json, X-DYLI-Timestamp (Unix seconds), and X-DYLI-Signature (hex HMAC-SHA256 of timestamp + "." + rawBody, keyed by the bridge secret). Sign the exact bytes sent. The receiver rejects signatures outside a five-minute window and bodies over 64 KiB.

{
"event": "paid",
"shop": "example.myshopify.com",
"orderId": "123456789",
"orderName": "#1001",
"reference": "DYL-SHOPIFY-ABC123",
"username": "collector",
"lines": [{ "sku": "CARD-001", "title": "Collector card", "quantity": 1, "variantId": "12345" }],
"feeCollected": "4.00",
"currency": "USD"
}

Only the trusted connector sends this request after validating Shopify's webhook, paid status, item quantities, fee payment, and warehouse destination. It is not proof of payment to DYLI. Username is resolved to an existing DYLI account server-side.

Responses and retries​

StatusMeaning
200Recorded or already recorded; ok: true and submissionId
400Invalid payload
401Invalid, missing, or stale signature
404DYLI username does not resolve
409Existing reference has different details, or cancellation arrived before creation
413Body too large
503Live receiver disabled
500Storage failure; retry the same reference

The unique shopify_external_id database index prevents duplicate submissions during concurrent retries. A payload hash rejects conflicting reuse of an existing reference. The connector persists delivery attempts, errors, and the returned DYLI submission ID and retries with backoff. Log-only mode makes no outbound submission requests.

Send event: "cancelled" with the same identifying fields to cancel an unprocessed submission. A processed submission is paused for manual review instead. Cancellation does not issue refunds or reverse inventory transfers.

Payment and warehouse boundaries​

The initial implementation creates an actual vault_requests row in a paused, unprocessed state. Item details and merchant-held fee amounts are in shopify_context and notes. total_cost remains zero because no DYLI payment has been made. Warehouse staff must review classification and settlement before processing. This endpoint never consumes Pro credit, charges a wallet, mints assets, or calls the 3PL vault-transfer endpoint.