How to Mark a Chargeback with the API

Admoji exposes three endpoints for recording a chargeback. Which one you call depends on whether you are recording it against a customer, a specific transaction, or a single order — they do different things, so pick deliberately.

PUT /api/v2/open/customers/mark-chargeback/{customerId} — marks the customer as a chargeback, blacklists them, and cancels their active recurring subscriptions.
POST /api/v2/open/customers/mark-chargeback — records a chargeback, a chargeback alert or a refund against a specific transaction, identified by its gateway transaction ID.
PUT /api/v2/open/orders/{orderId}/chargeback — sets a single order to Chargeback status and flags its transaction. It does not blacklist the customer and does not touch subscriptions.

Note: The API base endpoint is https://openapi.admoji.com. Every request needs an Authorization: ApiKey ... header — see How to Find your API Key.

Before You Start

Both endpoints require a valid API key, but they do not accept the same key types:

Full Access keys can call both endpoints.
Chargeback Defence keys can call the two customer endpoints (mark-chargeback) only. The order endpoint rejects them.
Any other key type is rejected by both.

A key with the wrong type gets an HTTP 403 with this body:

{
  "Status": 1,
  "Good": false,
  "Log": "Invalid ApiKey Type"
}

See API Key Types Explained for how to pick and create the right key.

Mark a Customer as Chargeback

Use this endpoint when you receive a chargeback notice and want to shut the customer down completely.

Request

PUT https://openapi.admoji.com/api/v2/open/customers/mark-chargeback/{customerId}

The customer ID goes in the URL path. There is no request body.

$ curl -X PUT 'https://openapi.admoji.com/api/v2/open/customers/mark-chargeback/12148089' \
  -H "Authorization: ApiKey secret_492796e421a34666a5695d53cd311111"

Response

{
  "Status": 0,
  "Good": true
}

What the Call Does

A successful call performs all of the following in one operation:

Sets the customer's chargeback flag.
Stamps the chargeback date of notice with the current UTC time.
Blacklists the customer so they cannot order again.
Cancels every active recurring subscription on the account (skipped if the customer was already cancelled).
Writes a chargeback entry to the customer log, attributed to the Open API.

Important: This call is not reversible from the API. Blacklisting and subscription cancellation take effect immediately.

Errors

Errors come back with HTTP 200 and "Status": 1 in the body:

{"Status": 1, "Good": false, "ErrorMessage": "Already marked as chargeback"} — the customer already carries the chargeback flag. The call is rejected rather than applied twice.
{"Status": 1, "Good": false, "ErrorMessage": "Customer not found or no permission"} — the customer ID does not exist, or it belongs to a different account than the one your API key is issued for.

Tip: Treat Already marked as chargeback as a success in your integration. It means the customer is already in the state you wanted, so retrying the call is safe.

Mark a Specific Transaction as Chargeback, Alert or Refund

Use this endpoint when your dispute management tool knows which transaction was disputed and needs to record what kind of dispute it was. It is the only one of the three that can record a chargeback alert or a refund, and the only one that accepts a note.

Request

POST https://openapi.admoji.com/api/v2/open/customers/mark-chargeback

$ curl -X POST 'https://openapi.admoji.com/api/v2/open/customers/mark-chargeback' \
  -H "content-type: application/json" \
  -H "Authorization: ApiKey secret_492796e421a34666a5695d53cd311111" \
  -d '{
    "CustomerID": 12148089,
    "Option": "cb",
    "GatewayTransactionID": "8f2c14a0-3b77-4e21-9c55-1d0e6a4b7f31",
    "IsRefund": false,
    "Note": "Chargeback received from Visa on 2026-08-20"
}'

Body Fields

CustomerID — required. The customer the transaction belongs to.
Option — required. One of cb (chargeback), cbalert (chargeback alert) or refund.
GatewayTransactionID — required. The gateway's transaction ID. It is matched against the customer's own orders, so it must belong to that customer.
IsRefund — optional. Also flags the customer as refunded when the option is cb or cbalert.
Note — optional. Appended to the customer log entry.

Response

{
  "Status": 0,
  "Good": true
}

What Each Option Does

cb — flags the customer and the matched transaction as a chargeback.
cbalert — flags the customer and the matched transaction as a chargeback alert.
refund — flags the customer as refunded. Nothing is blacklisted and no subscription is cancelled.

All three stamp the chargeback date of notice on both the customer and the transaction, and write an entry to the customer log attributed to the Open API.

Important: cbalert is not a soft option. Like cb, it blacklists the customer and cancels their active recurring subscriptions. Only refund leaves the account untouched.

Errors

{"Status": 1, "Good": false, "ErrorMessage": "Transaction not found"} — no order of that customer carries the GatewayTransactionID you sent.
{"Status": 1, "Good": false, "ErrorMessage": "Customer not found or no permission"} — the customer ID does not exist, or it belongs to a different account than the one your API key is issued for.

Note: Unlike the customer endpoint above, this one does not reject a customer who is already flagged — calling it twice applies the changes again. Guard against duplicate calls on your side.

Mark a Single Order as Chargeback

Use this endpoint when only one order was disputed and the rest of the customer's activity should stay untouched.

Request

PUT https://openapi.admoji.com/api/v2/open/orders/{orderId}/chargeback

The order ID goes in the URL path. There is no request body.

$ curl -X PUT 'https://openapi.admoji.com/api/v2/open/orders/1234567/chargeback' \
  -H "Authorization: ApiKey secret_492796e421a34666a5695d53cd311111"

Response

{
  "Status": 0
}

What the Call Does

Sets the order status and processing status to Chargeback.
Flags the order's transaction as a chargeback and as a chargeback alert, and stamps the chargeback date of notice with the current UTC time.
Fires the affiliate postback for the order status change, so any campaign postback subscribed to the Chargeback status trigger is sent.

Note: This endpoint does not blacklist the customer and does not cancel recurring subscriptions. If you need those effects, call the customer endpoint instead.

Errors

{"Status": 1, "Good": false, "ErrorMessage": "Order not found or no permission"} — the order ID does not exist, or it belongs to a campaign your API key is not authorized for.
403 with "Log": "Invalid ApiKey Type" — you used a Chargeback Defence key. This endpoint needs a Full Access key.

Which Endpoint Should You Use?

Use the customer endpoint when your dispute management tool receives a chargeback notice and your policy is to stop serving that customer. It is the one that matches what the platform does when an agent marks a chargeback from the customer profile.

Use the transaction endpoint when you know which transaction was disputed and need the record to say what kind of dispute it was — a chargeback, an alert, or a refund — or when you want to attach a note. Remember that cb and cbalert both blacklist the customer and cancel their subscriptions.

Use the order endpoint when you are reconciling individual disputed orders — for example, importing a chargeback file from your processor — and you want the order and its reporting to reflect the chargeback without cutting off the customer.

Tip: The two are not mutually exclusive. If a customer disputes one order and you also want them blacklisted, call the order endpoint for the specific order and then the customer endpoint for the account.

Verifying the Result

Open the customer profile in CRM > Customers. The chargeback flag and the log entry appear there.
Check the order in the customer's order list — its status reads Chargeback.
Chargeback counts and ratios roll into the reports — see How to Use the Income Report and How to Use the MID Health Report.

Related articles

Search

Admoji Help Center