Pull a merchant's Shopify underwriting data with a salted ephemeral token

POST/api/v1/credit/shopify-pull

For partners that hold the merchant's Shopify Admin API token in their own vault and pass it encrypted (PBKDF2-HMAC-SHA256 with a per-request random salt + AES-256-GCM bound to shop_domain + salted SHA-256 token_hash). DayZero decrypts the token only in memory, queries Shopify for orders, daily sales and refund summaries, disputes, and Shopify Capital balance transactions onto the merchant's DayZero business, and discards the plaintext token. Only the irreversible salted SHA-256 fingerprint (sha256:{salt}:{hash}) is stored in the database.

Operation ID: pull_credit_merchant_shopify·View as markdown·OpenAPI slice

Authentication

Bearer token authentication. Pass your DayZero API token in the Authorization header and the target business UUID in x-business-id.

Request body

Schema: ShopifyPullRequest

program_idstring: Your lending program id. Required without credit_line_id; with it, must match the line's program if sent.
external_merchant_idstring: Your id for the merchant, as sent on POST /credit/lines and POST /credit/bank-feeds. Required without credit_line_id.
credit_line_idstring: The merchant's open credit line id, when one already exists.
merchant_legal_namestring: Names the merchant's DayZero business when this call creates it. Ignored when the business already exists.
merchant_business_idstring: The merchant's existing DayZero business id, when already created by a bank feed or bank connection.
shop_domainstringrequired: The merchant's Shopify store domain (*.myshopify.com).
encrypted_tokenstringrequired: Base64 AES-256-GCM ciphertext of the Shopify Admin API access token, encrypted with the per-request salt and iv and bound to the normalized shop_domain as additional authenticated data.
saltstringrequired: Per-request random hex salt (16–32 bytes) used for PBKDF2-HMAC-SHA256 key derivation and the salted token_hash.
ivstringrequired: Hex initialization vector (12–16 bytes) for AES-256-GCM.
auth_tagstringrequired: 16-byte hex authentication tag produced by AES-256-GCM.
token_hashstringrequired: Salted SHA-256 hex digest of {salt}:{shop_domain}:{access_token} verifying token integrity after transport decryption.

Responses

201Successful Response

Schema: SuccessEnvelope_ShopifyPullResponse_

successboolean
messagestring
codestring
dataShopifyPullResponse

400Bad Request - Invalid input

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

401Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

403Forbidden - Insufficient permissions

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

404Not Found - Resource does not exist

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

422Validation Error

Schema: ErrorResponse

errorstringrequired: Error category: validation_error, unauthorized, forbidden, not_found, conflict, rate_limited, server_error, or service_unavailable.
messagestringrequired: Human-readable explanation, safe to show to end users.
codestringrequired: Stable machine-readable code in CATEGORY_NNN form (e.g. NOT_FOUND_006, AUTH_010, GEN_002).
request_idstring: Correlation id for support requests. Echoes the x-request-id request header when one was supplied.
errorsobject: Field-level validation messages keyed by field name. Present on 400/422 validation failures only.

Code samples

POST/api/v1/credit/shopify-pull

bash

curl -X POST 'https://api.ondayzero.com/api/v1/credit/shopify-pull' \
  -H 'Authorization: Bearer dz_your_token' \
  -H 'x-business-id: YOUR_BUSINESS_ID' \
  -H 'Content-Type: application/json' \
  -d '{
  "shop_domain": "string",
  "encrypted_token": "string",
  "salt": "string",
  "iv": "string",
  "auth_tag": "string",
  "token_hash": "string"
}'