> ## Documentation Index > Fetch the complete documentation index at: https://docs.staging.cope-demo.com/llms.txt > Use this file to discover all available pages before exploring further. # List chargebacks > Lists the business's chargebacks and chargeback reversals, newest first by `created_at`. A chargeback is a negative movement taken from you when a buyer disputed a sale; a reversal is the positive movement that returned it when the dispute was won. Each names its dispute by the processor's id, readable at GET /v1/commerce/disputes/{processor_id}. This resource follows the API convention: `{object, id}` references, `amount_minor_units`, millisecond UTC timestamps. Requires the `payments` permission at `read`. An API key holds a permission at the lower of its own level (`read` for a read-only key) and its holder's role; a key without it is refused with 403. ## OpenAPI ````yaml /api-reference/commerce-v1.openapi.json get /v1/commerce/chargebacks openapi: 3.0.3 info: description: >- Public REST API for COPE vendor integrations. Authenticate with a COPE API key and call the endpoints described below. title: COPE Public API version: v1 servers: - description: Production url: https://api.cope.com security: - cope_sk: [] paths: /v1/commerce/chargebacks: get: tags: - Chargebacks summary: List chargebacks description: >- Lists the business's chargebacks and chargeback reversals, newest first by `created_at`. A chargeback is a negative movement taken from you when a buyer disputed a sale; a reversal is the positive movement that returned it when the dispute was won. Each names its dispute by the processor's id, readable at GET /v1/commerce/disputes/{processor_id}. This resource follows the API convention: `{object, id}` references, `amount_minor_units`, millisecond UTC timestamps. Requires the `payments` permission at `read`. An API key holds a permission at the lower of its own level (`read` for a read-only key) and its holder's role; a key without it is refused with 403. operationId: commerce.chargebacks.list parameters: - description: >- Inclusive lower bound on created_at, ISO 8601. A bare date (YYYY-MM-DD) expands to the beginning of that day in UTC; a full date-time is used as given, and timezone-naive values are interpreted as UTC. in: query name: created_from required: false schema: type: string - description: >- Inclusive upper bound on created_at, ISO 8601. A bare date (YYYY-MM-DD) expands to the end of that day in UTC; a full date-time is used as given, and timezone-naive values are interpreted as UTC. in: query name: created_to required: false schema: type: string - description: >- Which payment methods to return: one name or several separated by commas (`card,sepa`). The names are the values `payment_method` carries: `card`, `klarna`, `affirm`, `sepa`, `ach`, `afterpay_clearpay`, `paypal`, `terminal`, `other`, `interac_present`, `kr_card`, `alma`, `billie`, `scalapay`, `sequra`, `sunbit`, `zip`, `acss_debit`, `au_becs_debit`, `bacs_debit`, `nz_bank_account`, `payto`, `ideal`, `bancontact`, `eps`, `fpx`, `giropay`, `p24`, `sofort`, `pay_by_bank`, `link`, `amazon_pay`, `cashapp`, `alipay`, `wechat_pay`, `grabpay`, `revolut_pay`, `mobilepay`, `twint`, `satispay`, `bizum`, `mb_way`, `kakao_pay`, `naver_pay`, `payco`, `samsung_pay`, `paypay`, `swish`, `blik`, `paynow`, `pix`, `promptpay`, `upi`, `boleto`, `konbini`, `multibanco`, `oxxo`, `crypto`, `customer_balance`, `stripe_balance`. Without it every payment method is returned. An unknown name or an empty element is refused with 422. in: query name: payment_method required: false schema: type: string - description: >- Which statuses to return: `pending`, `succeeded`, `failed`, or several separated by commas. Without it every status is returned. An unknown name or an empty element is refused with 422. in: query name: status required: false schema: type: string - description: >- Which rows to return: `chargeback`, `chargeback_reversal`, or both separated by a comma. Without it both are returned. A `chargeback_reversal` returns a chargeback's money to you when the dispute is won; its `amount_cents` is positive. An unknown name or an empty element is refused with 422. in: query name: type required: false schema: type: string - description: >- Page number for paginated results. Values below 1 and non-numeric values are ignored and the first page is returned; a page past the last one returns the last page. `current_page` is accepted as an older name for it and wins when both are sent. in: query name: page required: false schema: minimum: 1 type: integer - description: >- Number of records per page. Defaults to 12; values above 25 are clamped to 25; values below 1 and non-numeric values are ignored and the default is used. `items` and `limit` are accepted as older names for it, read only when `per_page` is absent. in: query name: per_page required: false schema: maximum: 25 minimum: 1 type: integer responses: '200': content: application/json: schema: additionalProperties: false properties: data: items: additionalProperties: false properties: amount_minor_units: description: >- In minor units of `currency`. NEGATIVE on a `chargeback` (taken from you), POSITIVE on a `chargeback_reversal` (returned to you). type: integer cash_flow_at: description: When the money moved, as the processor reported it. format: date-time nullable: true type: string created_at: description: When COPE recorded the movement. format: date-time type: string currency: type: string dispute: additionalProperties: false description: >- The dispute behind this movement, named by its processor's id: `GET /v1/commerce/disputes/{processor_id}`. Null only on a movement recorded without one. nullable: true properties: object: enum: - dispute type: string processor_id: description: >- The processor's dispute id: Stripe `du_...` or `dp_...`, PayPal `PP-D-...`. pattern: ^[A-Za-z0-9_-]{1,100}$ type: string required: - object - processor_id type: object disputed_payment: additionalProperties: false description: >- The sale the buyer disputed: `GET /v1/commerce/payments/{id}`. nullable: true properties: id: example: py_A1b2C3d4E5f6 pattern: ^py_[A-Za-z0-9]{8,32}$ type: string object: enum: - payment type: string required: - object - id type: object id: example: py_A1b2C3d4E5f6 pattern: ^py_[A-Za-z0-9]{8,32}$ type: string object: enum: - chargeback type: string order: additionalProperties: false description: The order of the disputed sale. properties: id: example: ord_A1b2C3d4E5f6 pattern: ^ord_[A-Za-z0-9]{8,32}$ type: string object: enum: - order type: string required: - object - id type: object payment_method: description: >- The payment method, one of the names the `payment_method` list filters take (`card`, `sepa`, `paypal`, `klarna` and the rest listed there). Null when none applies. nullable: true type: string payment_type: description: >- `chargeback`, or `chargeback_reversal` for the money of a won dispute coming back. enum: - chargeback - chargeback_reversal type: string reversal: additionalProperties: false description: >- The `chargeback_reversal` that returned this chargeback's money. Null unless `reversed`. nullable: true properties: id: example: py_A1b2C3d4E5f6 pattern: ^py_[A-Za-z0-9]{8,32}$ type: string object: enum: - chargeback type: string required: - object - id type: object reversed: description: >- True when the dispute was won and the money came back: `reversal` names the movement that returned it. Always false on a `chargeback_reversal`. type: boolean reversed_chargeback: additionalProperties: false description: >- On a `chargeback_reversal`, the chargeback it reverses. Null on a chargeback. nullable: true properties: id: example: py_A1b2C3d4E5f6 pattern: ^py_[A-Za-z0-9]{8,32}$ type: string object: enum: - chargeback type: string required: - object - id type: object status: description: >- `pending`, `succeeded` or `failed`. A chargeback is recorded when the processor takes the money, so it is normally `succeeded`. type: string required: - object - id - status - payment_type - payment_method - amount_minor_units - currency - cash_flow_at - created_at - order - disputed_payment - dispute - reversed - reversal - reversed_chargeback type: object type: array pagination: additionalProperties: false properties: current_page: type: integer per_page: type: integer total_count: type: integer total_pages: type: integer required: - total_pages - current_page - per_page - total_count type: object required: - data - pagination type: object description: Successful response '400': content: application/problem+json: examples: unparsable_request: summary: Unparsable request value: code: invalid_request detail: >- The request could not be parsed. Check the query string and the request body. request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90 status: 400 title: Invalid Request type: https://docs.cope.com/errors/invalid_request schema: $ref: '#/components/schemas/PublicProblemDetail' description: Invalid request '401': content: application/problem+json: schema: $ref: '#/components/schemas/PublicProblemDetail' description: Missing or invalid bearer token '403': content: application/problem+json: schema: $ref: '#/components/schemas/PublicProblemDetail' description: Bearer token is not authorized for this route '422': content: application/problem+json: examples: validation_failed: summary: Validation failed value: code: validation_failed detail: Name can't be blank errors: - code: blank detail: Name can't be blank param: name request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90 status: 422 title: Validation Failed type: https://docs.cope.com/errors/validation_failed schema: $ref: '#/components/schemas/PublicProblemDetail' description: One or more query parameters failed validation '503': content: application/problem+json: examples: user_not_ready: summary: The key's user is not available yet value: code: user_not_ready detail: Retry after 2 seconds errors: - code: user_not_ready detail: Retry after 2 seconds request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90 status: 503 title: User Not Ready type: https://docs.cope.com/errors/user_not_ready tenant_not_ready: summary: The key's business is not available yet value: code: tenant_not_ready detail: Retry after 2 seconds errors: - code: tenant_not_ready detail: Retry after 2 seconds request_id: 0b6e3f2a-8c4d-4f1e-9a7b-5d2c8e1f4a90 status: 503 title: Tenant Not Ready type: https://docs.cope.com/errors/tenant_not_ready schema: $ref: '#/components/schemas/PublicProblemDetail' description: >- The API key is valid but its user or business is not available to this API yet (`user_not_ready`, `tenant_not_ready`). Retry after the `Retry-After` seconds. security: - cope_sk: [] components: schemas: PublicProblemDetail: additionalProperties: false properties: code: type: string detail: nullable: true type: string errors: items: additionalProperties: false properties: code: type: string detail: type: string param: type: string required: - code - detail type: object type: array request_id: description: >- Correlates this response with COPE's logs; the response also carries it as `X-Request-Id`. It is the `X-Request-Id` you sent when that is 1-128 letters, digits, `_`, `@` or `-`, and otherwise one COPE generated. Quote it when you contact support. type: string status: type: integer title: type: string type: type: string required: - type - title - status - code - request_id type: object securitySchemes: cope_sk: description: >- Bearer credential for the public API: a live COPE API key (`ck_live_*`; keys issued earlier as `cope_sk_live_*` keep working). Dashboard sign-in tokens are not accepted. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.