Report payments and refunds

POST/v1/api/store/{team_slug}/report/payment

v1Operation ID v1_public_report_payment

Returns every payment and refund recorded in the period on a sales order or quote that still exists, with its order, and every payment customers made in the Customer Portal. Use it to reconcile what you received.

Each row is a payment record (the shape of an order's payment list) plus six order fields: amount is in thousandths, an older encoding (339750 is 339.75; refunds are negative), date is ISO 8601, order_id is the order's hash id while order_scoped_id is its number, and invoices is a list of the order's invoice numbers. (The CSV export from the web app formats these differently.)

A Customer Portal payment produces one row however many orders it paid. On all Customer Portal rows, warehouse, order_scoped_id, order_name, and created_by are null; invoices lists the invoices it was applied to, and orders lists the orders. Later provider changes (such as refunds) add an adjustment row signed like the change.

Kind of payment row	`subtype` / `action`	Has `order_id`	Fields that are `null`
Standard order payment	`subtype: PAYMENT`	Yes	None (order fields populated)
Customer Portal (single order)	`subtype: PAYMENT`<br>`action: CUSTOMER_CHECKOUT`	Yes	`warehouse`, `order_scoped_id`, `order_name`, `created_by`
Customer Portal (multi-order funding)	`subtype: CUSTOMER_CHECKOUT_FUNDING`	No (`null`)	`warehouse`, `order_scoped_id`, `order_name`, `created_by`
Customer Portal funding adjustment	`subtype: CUSTOMER_CHECKOUT_FUNDING_ADJUSTMENT`	No (`null`)	`warehouse`, `order_scoped_id`, `order_name`, `created_by`

Permission

Needs the View Reports permission. Otherwise 403 with a bare { "message": "Insufficient Permission" } (no success or error envelope).

Business rules

A payment or refund is in the period when it was recorded (created) between start_date and end_date, inclusive.
Payments on a quote that became a sales order stay in the report. Payments on deleted orders are left out, except CUSTOMER_CHECKOUT_FUNDING rows and their adjustments, which are listed whatever happened to the orders.
Only gateway, manual and Customer Portal payments and refunds are listed (lost disputes count as refunds): payments from customer credit, refunds to customer credit, and the moves that apply a Customer Portal payment to its orders are left out. Rows come newest first.

Path parameters

team_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team

Request body

application/json, required.

end_datestring (date-time)required
End of the period (ISO 8601), inclusive: send 23:59:59 to include the whole last day. In UTC, like start_date (an offset is dropped, not applied).
start_datestring (date-time)required
Start of the period (ISO 8601), inclusive, to the second: send the start of the day. Send it in UTC (Z): the date and time are compared with UTC as written and any offset is dropped, so 2026-10-01T00:00:00-05:00 means midnight UTC.

Response

200Successful response.

dataarray of objectsrequired
Fields of each item (33)
- actionstring | null
  How it was made, for example a gateway name.
- amountinteger | number | string | null
  The amount. Refunds are negative. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- created_bystring | null
  Name of who created the order.
- customer_idstring | null
  The customer.
- customer_namestring | null
- customer_payment_funding_idstring | null
  Customer Portal payment rows only: the customer payment.
- datestring (date-time)
  When it was recorded. ISO 8601 with offset.
- directionstring
  INCREASE for a payment, DECREASE for a refund; a Customer Portal adjustment carries its own direction.
  - One of: "INCREASE", "DECREASE"
- has_open_holdboolean
  Card and Customer Portal payments: true while a dispute (or review) is open.
- idstring
  The payment record.
- invoicesarray of strings
  The order's invoice numbers (all of them, not only those this payment paid). On Customer Portal payment rows: the invoices the payment was applied to.
- is_deletableboolean
- is_editableboolean
- is_external_cash_movementboolean
  Customer Portal payment rows only: true for the customer's payment and its later changes.
- order_idstring | null
  The order's hash id (not its number: that is order_scoped_id).
- order_namestring | null
  The order name.
- order_scoped_idstring | null
  The order number.
- ordersarray of objects
  Customer Portal payment rows only: the orders the payment was applied to (empty when they can't be found).
  Fields of each item (4)
  - invoice_applicationsarray of objects
    Fields of each item (3)
    invoice_idstring | null
    The invoice's unique key.
    invoice_referencestring | null
    The invoice number.
    original_applied_amountstring | null
    What was first applied to this invoice, in currency units. A decimal string, such as "100.0000"; parse it as a decimal.
  - order_idstring
    The order's unique key (ord_…), not its hash id.
  - order_referencestring | null
    The order number when it was paid.
  - original_applied_amountstring | null
    What the payment first applied to this order, in currency units (not thousandths). A decimal string, such as "100.0000"; parse it as a decimal.
- payment_freeze_reasonstring | null
  STRIPE, PAYPAL and SQUARE_V2 card payments and direct Customer Portal payments: chargeback_open or payment_under_review while a dispute or review freezes it, otherwise null.
- payment_gatewaystring | null
  The gateway, for a gateway payment or refund; null otherwise.
- payment_gateway_sourcestring | null
  Only on gateway payments and refunds: the card source the gateway reported (Square), or null.
- payment_method_idstring | null
  The payment method.
- payment_noticesarray of objects
  Card and Customer Portal payments: one notice per open dispute, as on an order's payment list.
- reference_descriptionstring | null
- reference_idstring | null
- refundable_amountinteger | number | string | null
  For a payment, what can still be refunded (0 when the method doesn't support refunds); 0 for a refund. Thousandths, an older encoding: 12500 is 12.50. Usually a whole number; an amount finer than a thousandth comes back as a number with a fraction (1234.5 is 1.2345), or as a string ("1234.5") when you send X-Yoprint-Decimal-Format: exact-v1. See Money and quantities.
- related_transactionstring | null
  For a refund, the id of the payment it refunds; null otherwise.
- subtypestring
  CUSTOMER_CHECKOUT_FUNDING is a Customer Portal payment that paid several orders; CUSTOMER_CHECKOUT_FUNDING_ADJUSTMENT a later change to one (its action names the kind, for example CUSTOMER_CHECKOUT_REFUND).
  - One of: "PAYMENT", "REFUND", "CUSTOMER_CHECKOUT_FUNDING", "CUSTOMER_CHECKOUT_FUNDING_ADJUSTMENT"
- tokenstring | null
  A gateway reference, on some gateway payments; null otherwise.
- typestring
  MANUAL (recorded by hand) or SYSTEM (recorded by a payment gateway).
- user_idstring | null
  Who recorded it.
- voidedboolean
- warehousestring | null
  The order's warehouse label.
statusintegerrequired
successbooleanrequired

Errors

401The API key is missing or wrong (unauthenticated).
403You are not allowed to do this. api_access_not_in_plan: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only {"message": "Insufficient Permission"}. Other refusals use the error envelope, with unauthorized or user_is_not_authorized.
When
Your role lacks View Reports.
Fix
Ask the team owner to turn on View Reports for your permission group.
404Not found. page_not_found: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. code: null, with a message that starts "No query results for": there is no record with that id.
422The request was refused and changed nothing. validation_failed lists what to fix in error.fields; other codes name a business rule, explained in error.message. A few checks answer with only {"message": "..."}. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer connect_timeout ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
When
start_date or end_date is missing or not ISO 8601.
Fix
Send both as ISO 8601 date-times.

Notes

There is no paging: the whole period comes back in one response. Ask for a month or less at a time.

POSTReport invoices of orders paid in full/v1/api/store/{team_slug}/report/tax
GETList the payments of a sales order/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment

Example request

curl

curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/report/payment' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "end_date": "2026-11-30T23:59:59Z",    "start_date": "2026-11-01T00:00:00Z"  }'

Example response 200

{
  "data": [
    {
      "action": "ORDER_PAYMENT",
      "amount": 100000,
      "created_by": "Alex Rivera",
      "customer_id": "ifAHmADekGZ6id",
      "customer_name": "Northwind Apparel",
      "date": "2026-11-03T14:30:00+00:00",
      "direction": "INCREASE",
      "id": "hAwWd7vPrqjuHD",
      "invoices": [
        "1001"
      ],
      "is_deletable": true,
      "is_editable": true,
      "order_id": "sFbALVSYD55eXe",
      "order_name": "Team shirts",
      "order_scoped_id": "SO1001",
      "payment_gateway": null,
      "payment_method_id": "Kst6z3ULXLBrmN",
      "reference_description": null,
      "reference_id": "CHK-1001",
      "refundable_amount": 100000,
      "related_transaction": null,
      "subtype": "PAYMENT",
      "token": null,
      "type": "MANUAL",
      "user_id": "4mdDkMg3dgQOa3",
      "voided": false,
      "warehouse": null
    }
  ],
  "status": 200,
  "success": true
}

AI agents: read /llms.txt; add .md to any page URL for its Markdown. Guides and concepts in one file: /llms-full.txt.

Download the OpenAPI spec Support: support@yoprint.com yoprint.com