List a customer's credit history

GET/v1/api/store/{team_slug}/customer/{hash_id}/credit

v1Operation ID v1_public_customer_credit_index

Lists the customer's credit entries, newest first: credit added or taken out by hand, credit used to pay sales orders, sales order payments refunded to credit, Customer Portal payments received into credit and later changes to them, overpayments from online payments moved into credit or refunded from it, credit a refund took back, and credit given back when that refund failed (see type, subtype and action). Together they add up to the customer's wallet_fund. credit_source says where credit came from or went.

This list reads per_page (1 to 100; the team's page size when left out) as well as page.

Permission

Any member of the team.

Path parameters

team_slugstringrequired
Your team slug, shown as Team ID next to your API key in Profile.
- Example your-team
hash_idstringrequired
The customer's id (id from List customers or Create a customer). A hash id from an earlier answer; unique keys and document numbers (such as PO0042) don't work here.
- Example EDhVUaC6jbLbed

Query parameters

pageinteger
The page to return.
- Default 1
- Minimum 1
- Example 1
per_pageinteger
Entries per page, 1 to 100. Without it, the team's page size (pagination_per_page in team settings, 50 unless changed).
- Minimum 1
- Maximum 100
- Example 25

Request body

This operation takes no request body.

Response

200Successful response.

dataarray of objectsrequired
Fields of each item (37)
- actionstringrequired
  The specific action that created the entry:
  
  Manual entries:
  - CUSTOMER_DEPOSIT: credit added by hand (created by this API).
  - CUSTOMER_WITHDRAW: credit taken out by hand (created by this API).
  - CUSTOMER_CREDIT_WITHDRAW: credit used to pay a sales order.
  - CUSTOMER_CREDIT_DEPOSIT: a sales order payment refunded to credit.
  System entries:
  - CUSTOMER_CHECKOUT_FUNDING: a Customer Portal payment received into credit.
  - CUSTOMER_CHECKOUT_<KIND>: an adjustment to a portal payment (such as CUSTOMER_CHECKOUT_REFUND).
  - CUSTOMER_CREDIT_RECOVERY: credit a refund took back.
  - CUSTOMER_CREDIT_RESTORED: credit restored after a failed refund.
  - Overpayment actions for CUSTOMER_SPILLED_OVER_* entries.
- amountinteger | number | stringrequired
  Positive for credit added, negative for credit taken out. 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.
- credit_sourceobject | nullrequired
  Where the credit came from or went: on credit issued from a payment, credit applied to a sales order, and credit a refund or a lost dispute took back or gave back. Null on other entries.
  Child fields (5)
  - customer_payment_funding_idstring | nullrequired
    The Customer Portal payment's key, when the credit came from one. Null otherwise.
  - kindstringrequired
    issued: credit issued from a sales order payment. returned: Issue credit took back credit a Customer Portal payment had left on the order. order_deleted_credit: issued credit whose sales order was later deleted. applied: credit applied to a sales order. refund: credit the customer had already spent, owed back after a refund. credit_used_for_refund and credit_taken_back: credit a refund took back without making the balance negative; nothing is owed. refund_failed: that credit given back because the refund failed. chargeback: taken back by a lost dispute. refund_and_chargeback: taken back by a lost dispute after a refund during it. order_deleted: taken back for a deleted sales order.
    One of: "issued", "returned", "order_deleted_credit", "applied", "refund", "credit_used_for_refund", "credit_taken_back", "refund_failed", "chargeback", "refund_and_chargeback", "order_deleted"
  - order_hash_idstring | nullrequired
    The sales order's id. Null when no single order is involved, or when the order of an applied entry was deleted.
  - order_referencestring | nullrequired
    That sales order's number, such as SO1001. Not an id.
  - payment_labelstringrequired
    The payment the credit came from, as YoPrint names it, such as "Stripe payment", "Cash payment" or "Customer credit".
- datestring (date-time)required
  When the entry was made.
- directionstringrequired
  Whether the entry added credit or took it out.
  - One of: "INCREASE", "DECREASE"
- idstringrequired
- subtypestringrequired
  The category of the credit entry:
  - TRANSFER: all MANUAL entries.
  - CUSTOMER_CHECKOUT_FUNDING: a Customer Portal payment received into customer credit.
  - CUSTOMER_CHECKOUT_FUNDING_ADJUSTMENT: a later change to a portal payment, such as a refund or lost dispute.
  - CUSTOMER_SPILLED_OVER_GATEWAY_PAYMENT: an online payment overpayment moved into credit.
  - CUSTOMER_SPILLED_OVER_GATEWAY_PAYMENT_REFUND: a refund of an overpayment.
  - CUSTOMER_SPILLED_OVER_GATEWAY_REFUND: an online refund overpayment moved into credit.
  - CUSTOMER_CREDIT_RECOVERY: credit a refund took back.
  - CUSTOMER_CREDIT_RESTORED: credit given back because that refund failed.
  - One of: "TRANSFER", "CUSTOMER_CHECKOUT_FUNDING", "CUSTOMER_CHECKOUT_FUNDING_ADJUSTMENT", "CUSTOMER_SPILLED_OVER_GATEWAY_PAYMENT", "CUSTOMER_SPILLED_OVER_GATEWAY_PAYMENT_REFUND", "CUSTOMER_SPILLED_OVER_GATEWAY_REFUND", "CUSTOMER_CREDIT_RECOVERY", "CUSTOMER_CREDIT_RESTORED"
- typestringrequired
  Whether the entry was made by a person or by YoPrint:
  - MANUAL: credit added or taken out by hand, credit used to pay a sales order, and sales order payments refunded to credit.
  - SYSTEM: entries YoPrint creates automatically, including Customer Portal payments received into credit and their adjustments (such as refunds), online overpayments, and credit recovered or restored.
  - One of: "MANUAL", "SYSTEM"
- credit_source_payment_idstring | null
  Those two kinds only: the id of the sales order payment the credit came from.
- currency_isostring | null
  Customer Portal payment entries only: the payment's currency, such as USD.
- customer_idstring | null
- customer_payment_application_idstring | null
- customer_payment_checkout_idstring | null
  Customer Portal payment entries only: the key of the checkout the payment was made in, or null.
- customer_payment_funding_idstring | null
  Customer Portal payment entries only (CUSTOMER_CHECKOUT_*, and credit applied from such a payment): the payment's key.
- customer_payment_source_kindstring | null
  Customer Portal payment entries only: what the entry is, for example funding for the payment, the kind of change for an adjustment (such as refund), or application for credit applied from it.
- customer_payment_sourcesarray of objects
  Customer Portal payment entries only: the Customer Portal payments the entry draws on, when it lists them; empty otherwise.
  Fields of each item (4)
  - amountstring | null
    A decimal string, such as "25.00"; parse it as a decimal.
  - currency_isostring | null
  - customer_payment_funding_idstring | null
  - funding_transaction_idstring | null
- funding_payment_gatewaystring | null
  Customer Portal payment entries only: the payment's provider, as in payment_gateway.
- funding_transaction_idstring | null
  Customer Portal payment entries only: the id of the payment's CUSTOMER_CHECKOUT_FUNDING entry.
- has_open_holdboolean
  Customer Portal payment entries only: true while the payment is held, for example by an open dispute, or when YoPrint could not read the payment.
- is_deletableboolean
- is_editableboolean
- is_external_cash_movementboolean
  Customer Portal payment entries only: true when money moved through the provider (the payment and its adjustments), false for credit moved inside YoPrint.
- order_idnull
  Always null on customer credit entries, also for credit used on or refunded from a sales order. credit_source names the order where there is one.
- payment_gatewaystring | null
  The payment provider for entries that moved money through one: for a Customer Portal payment, STRIPE, PAYPAL, SQUARE_V2, AUTHORIZE_NET or CHARGE_IT_PRO. Null otherwise.
- payment_method_idstring | null
- payment_noticesarray of objects
  Customer Portal payment entries only: why the payment needs attention, such as dispute_open, dispute_under_review or payment_needs_attention.
  Fields of each item (3)
  - codestring
  - customer_payment_funding_idstring | null
  - next_actionstring | null
- provider_refund_referencestring
  Only on a Customer Portal payment refund that has one: the provider's refund reference.
- recovery_kindstring | null
  CUSTOMER_CREDIT_RECOVERY and CUSTOMER_CREDIT_RESTORED entries only: credit_consumed when unspent credit was taken back, negative_credit when spent credit was taken back and the balance went below zero.
  - One of: "credit_consumed", "negative_credit"
- reference_descriptionstring | null
- reference_idstring | null
  Your reference; on a Customer Portal payment adjustment, the payment provider's reference.
- refundable_amountinteger | number | string
  How much of it can still be refunded; 0 for credit entries. 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
  The entry this one belongs to: for a refund, the payment; for CUSTOMER_CREDIT_RECOVERY and CUSTOMER_CREDIT_RESTORED, the refund; for a Customer Portal payment adjustment, its CUSTOMER_CHECKOUT_FUNDING entry. Null otherwise.
- restores_transaction_idstring | null
  CUSTOMER_CREDIT_RESTORED only: the CUSTOMER_CREDIT_RECOVERY entry it gives back.
- reversal_transaction_idstring | null
  CUSTOMER_CREDIT_RESTORED only: the entry that recorded the failed refund.
- tokenstring | null
- user_idstring | null
  Who made it.
- voidedboolean
statusintegerrequired
successbooleanrequired
paginationobject
Child fields (6)
- countintegerrequired
- currentPageintegerrequired
- linksobject | array of anyrequired
  Links to the neighbouring pages: previous and next, each present only when that page exists. An empty list, [], when there is only one page.
  Child fields (2)
  - nextstring (uri)
    The next page.
  - previousstring (uri)
    The previous page.
- perPageintegerrequired
- totalintegerrequired
- totalPagesintegerrequired

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.
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.
When
No live customer with this id: deleted customers are not found here. error.code is null and error.message names the record type.
Fix
Check the 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
per_page is over 100 or below 1, or page is below 1. error.code is validation_failed.
Fix
Send per_page 1 to 100 and page 1 or more.

POSTAdd or take out customer credit/v1/api/store/{team_slug}/customer/{hash_id}/credit
GETGet a customer credit entry/v1/api/store/{team_slug}/customer/{hash_id}/credit/{id}

Example request

curl

curl 'https://secure.yoprint.com/v1/api/store/your-team/customer/EDhVUaC6jbLbed/credit' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1'

Example response 200

{
  "data": [
    {
      "action": "CUSTOMER_DEPOSIT",
      "amount": 50000,
      "credit_source": null,
      "customer_id": "V4keXwwxMQyXw7",
      "date": "2026-11-01T09:00:00+00:00",
      "direction": "INCREASE",
      "id": "mJ3uYS5OJQ9VEq",
      "is_deletable": true,
      "is_editable": false,
      "order_id": null,
      "payment_gateway": null,
      "payment_method_id": "6nz3Vu9sFR4dxM",
      "reference_description": null,
      "reference_id": "CHQ-1001",
      "refundable_amount": 0,
      "related_transaction": null,
      "subtype": "TRANSFER",
      "token": null,
      "type": "MANUAL",
      "user_id": "lOURnovd3hkIQI",
      "voided": false
    }
  ],
  "pagination": {
    "count": 1,
    "currentPage": 1,
    "links": [],
    "perPage": 50,
    "total": 1,
    "totalPages": 1
  },
  "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