Product
Solutions
Pricing
Resources
Company
Ask a question Install for Shopify
DEVELOPERS

One endpoint, and it points inward.

There is no outbound API. You cannot read cases back out over HTTP, and this page used to say otherwise at some length. What exists is a single signed intake, for merchants who already subscribe to a third-party pre-dispute alert feed and want it to reach the app as well.

Most merchants never touch it. Disputes arrive from Shopify Payments on their own, which needs no integration at all. If you want your data out, the savings ledger exports to CSV.

POST /api/alerts

Signed with HMAC-SHA256 over the literal string <timestamp>.<raw body>, keyed with a shared secret, hex encoded. The timestamp is inside the signed material and must be within five minutes of the server clock, so a captured request stops working almost immediately.

HEADERS
Content-Type application/json
X-Chargebackify-Timestamp Unix seconds. Signed, and checked for age.
X-Chargebackify-Signature Hex HMAC. A sha256= prefix is also accepted.
BODY
alert_id required Your identifier. Redelivering it updates the case rather than opening a second one.
network required visa or mastercard, case-insensitive. Anything else is refused.
reason required The cardholder's reason, in their bank's words. Shown verbatim.
descriptor required The statement descriptor. This is how the alert finds its shop.
amount required The disputed amount, e.g. "128.00".
deadline_at required ISO 8601. After this instant the case can no longer be resolved.
currency optional Three letters. Defaults to USD.
card_last4 optional Digits only. Without it, matching falls back to amount and date and is much weaker.
transaction_at optional ISO 8601. Narrows the order search. Defaults to now.
dispute_fee optional The processor's flat dispute fee. Defaults to 15.00.
RESPONSES
200 {"status":"accepted"} Case opened. It may already have been refunded automatically.
200 {"status":"duplicate"} Known alert_id. Deadline and reason refreshed, no second case.
200 {"status":"ignored"} A final answer, not a transient failure. The body names the reason: descriptor_not_enrolled, shop_not_installed, network_coverage_off, deadline_passed or unusable_amount. Retrying gives the same result.
401 — Bad or stale signature. Nothing is created.
400 — Malformed JSON, or a body that fails validation.
429 — Rate limited. Honour Retry-After.
503 — No shared secret is configured, so the endpoint refuses everything. An intake with no secret would let anyone make the app refund orders.
What happens after acceptance

The descriptor has to resolve to exactly one shop — a descriptor claimed by two routes to neither, because sending a refund to the wrong merchant is worse than dropping the alert. Candidate orders are then fetched by card last four and filtered on the original order total, so an order that was already refunded still shows up rather than silently vanishing. One qualifying order is an exact match, several is partial, none is no match. Your rules decide the rest.

Want the secret?

Write to support@chargebackify.com and tell us which feed you are sending from. An alert makes this app refund an order, so the secret goes to you and to nobody else.

Get in touch

Chargeback prevention infrastructure, starting with Shopify. Alerts, refunds and ratio monitoring in one place.

The Prevention Brief

Network rule changes, threshold updates and merchant teardowns. Once a month.

No spam. Unsubscribe anytime.

PRODUCT
How it worksChargeback alertsAutomatic refundsOrder matchingRatio monitoringChargebackify vs ChargeflowChargebackify vs DisputifierChargebackify vs SignifydChargebackify vs NoFraudChargebackify vs JusttPricing
SOLUTIONS
High-risk merchantsSubscriptionsDropshippingHigh-volume DTCAgenciesEnterprise
RESOURCES
BlogHelp centerFAQGlossaryAPI docsCustomer storiesIntegrations
FREE TOOLS Savings calculatorRatio checkerDescriptor checkerReason code lookupDeadline calculatorVendor comparison
INTEGRATIONS
ShopifyShopify PaymentsDispute intake API
COMPANY
AboutCareersContactBook a demoPressLog in
LEGAL
Terms of servicePrivacy policySecurityComplianceDPACookie settings
© 2026 Chargebackify
For Shopify Payments stores English (US)