DisputesService class (accessed via client.disputes) lets a shopper raise and track a dispute on one of their own marketplace orders when something goes wrong — the item never arrived, arrived damaged, or was not as described.
How disputes work in Galactic Core
Disputes are a marketplace capability. On a marketplace, the operator sits between the shopper and the merchant. When a shopper opens a dispute, the operator reviews it and applies a resolution — a refund, store credit, or another remedy — and the merchant is kept in the loop. This API is the shopper’s side of that flow: open a dispute, list and track your own disputes, add a message to the conversation, and cancel one you opened while it is still open. Reviewing and resolving a dispute is an operator and merchant task handled in the admin dashboards, not through this API. There is no “resolve” or “refund” method on this service — the resolution is the operator’s decision. A storefront opens disputes and reacts to the outcome.A dispute moves through a lifecycle
A dispute is created withstatus: "open". As the operator works through it the status moves to under_review, and can pause on awaiting_buyer or awaiting_seller while more information is gathered. It ends in one of three terminal states: resolved (the operator applied a remedy), rejected (the operator found in the seller’s favour), or cancelled (the shopper withdrew it). Once a dispute reaches a terminal state it can no longer be cancelled or messaged.
When the operator resolves a dispute, resolution and resolution_amount describe the outcome — for example refund_partial with an amount, store_credit, or release_to_seller — so your storefront can show the shopper what happened.
Every dispute has a conversation thread
Opening a dispute starts a message thread (thread_id) shared by the shopper, merchant, and operator. Use addDisputeMessage to let the shopper add detail or respond while the dispute is being reviewed.
One open dispute per order
A shopper can have only one open dispute on a given order at a time. Opening a second while one is still open returns a409 Conflict.
Authentication
Every endpoint takes an API key in theAuthorization: Bearer header. The reason-code list (listDisputeReasons) needs only the API key, so you can build the reason picker before the shopper signs in. Every other method also requires a customer session identifying the signed-in shopper — either x-auth-token (a GC-native session token from client.auth.login / client.auth.verifyOtp) or x-external-auth (a bring-your-own-auth assertion). A shopper can only open, list, track, message, and cancel their own disputes.
On a marketplace storefront that holds an operator key rather than a single merchant’s key, pass storeId (the merchant the shopper is acting at) so the call resolves against that merchant.
On a marketplace the shopper holds no customer record with the merchant, so ownership is decided by the order: it must belong to a purchase the shopper placed with their credential, or a guest purchase made with an email address they have verified. The dispute records the shopper’s own credential, and only that credential can read, message or cancel it. When the operator decides a dispute as credit, the amount is added to the shopper’s marketplace wallet, which client.marketplace.getMarketplaceWallet returns.
Methods
listDisputeReasons()
Returns the reason codes accepted when opening a dispute, each with a human-readable label for a dropdown. Only an API key is required.
listDisputes({ status?, limit?, storeId?, xAuthToken? / xExternalAuth? })
Lists the signed-in shopper’s disputes, newest first. Optionally filter by status.
openDispute({ requestBody, storeId?, xAuthToken? / xExternalAuth? })
Opens a dispute against one of the shopper’s own orders. order_id must be an order that belongs to the signed-in shopper. reason is one of the reason codes; when it is other, a description is required. Returns the new dispute’s id, status, and thread_id.
getDispute({ id, storeId?, xAuthToken? / xExternalAuth? })
Retrieves one of the shopper’s own disputes, including its current status and — once resolved — the resolution and resolution_amount.
addDisputeMessage({ id, requestBody, storeId?, xAuthToken? / xExternalAuth? })
Adds a message from the shopper to the dispute’s conversation thread. Fails with 409 Conflict if the dispute is already closed.
cancelDispute({ id, storeId?, xAuthToken? / xExternalAuth? })
Cancels one of the shopper’s own disputes while it is still open — for example if the parcel turned up. A resolved or rejected dispute cannot be cancelled (409 Conflict).