Move part of an order's payments to customer credit

POST/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/credit/refund_to_customer_credit

v2Operation ID v2_public_sales_order_credit_refund_to_customer_credit

Takes some of what the customer paid on this order and keeps it as their credit, to use on another order. Send a whole number of thousandths: 12500 is 12.50. See Money and quantities. The answer is the order's new credit entry: subtype TRANSFER, action ORDER_CREDIT_WITHDRAW, direction DECREASE and a negative amount (25.00 is -25000). {hash_id} is the order's id (for example V4keXwwxMQyXw7); the ord_ unique key is not accepted here.

Permission

Needs permission to see this order's finances and to change it: the team owner; or a role with view_order_finance (View Sales Order Pricing) and view_all_order (or view_self_order, for orders the user created or is assigned to), and update_all_order (or update_self_order, for orders the user created or is assigned to). Otherwise 403 with a short body, {"message": "No permission to change this order payment."}. The order must be published.

Business rules

• The order must have money paid on it: otherwise 422 "Insufficient Order Balance".
• Only money not allocated to an invoice can move. Payments are allocated when they are recorded, so delete those payment links first, or use Move all of an order's payments to customer credit. Otherwise 422 "Amount To refund is greater than the order payment total"; 0 gives "Amount To refund cannot be Zero". The sign is ignored.
• Money of a frozen payment (an open dispute or review) never moves. With nothing else left, the freeze 422 refuses it; when the amount is more than the rest, 422 issue_credit_amount_above_available ("Amount To refund is greater than the money available on this order. Part of it is held by an open dispute."), with error.available_amount in thousandths.
• Money the order holds from a Customer Portal payment is moved first, as credit tied to that payment, then the rest. If too little ordinary money is left, the call is refused with 422 validation_error and the message "CUSTOMER_PAYMENT_SOURCE_FUNDS_UNAVAILABLE".
• Only published orders: otherwise 422 "Action Not Allow".

Side effects

• Raises the customer's credit and lowers the order's paid amount; updates invoices and customer totals.

Path parameters

• team_slugstringrequired

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

  • Example your-team
• hash_idstringrequired

  The sales order's or quote's id (a hash id). The ord_ unique key and the order number do not work here.

  • Example V4keXwwxMQyXw7

Request body

application/json, required.

• amountintegerrequired

  How much to move. Send a whole number of thousandths of the currency: 12500 is 12.50. Must not be 0. A number with decimals is refused with 422 validation_failed: error.fields.amount says "The amount must be a whole number of thousandths of the currency unit, such as 12500 for 12.50.".

• reference_descriptionstring

  A note for the record.

Response

200Successful response.

• dataobjectrequired

  A payment, refund or credit move. Customer Portal rows (action CUSTOMER_CHECKOUT, and credit applied from a Customer Portal payment) also carry customer_payment_checkout_id, funding_transaction_id, customer_payment_application_id, customer_payment_source_kind, is_external_cash_movement and currency_iso.

  Child fields (36)

  • amountinteger | number | string | nullrequired

    Signed: negative for DECREASE (a 25.00 refund is -25000). 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.

  • idstringrequired
  • actionstring | null

    ORDER_PAYMENT, ORDER_REFUND, ORDER_CREDIT_DEPOSIT (paid from customer credit), ORDER_CREDIT_WITHDRAW (moved to customer credit), ORDER_CREDIT_RECOVERY, ORDER_CREDIT_RESTORED, CUSTOMER_CHECKOUT (paid in the customer portal, and its refunds), CUSTOMER_CHECKOUT_CHARGEBACK (a lost dispute), or the gateway: STRIPE, SQUARE, SQUARE_V2, PAYPAL, AUTHORIZE_NET, CHARGE_IT_PRO. A REFUND_REVERSAL carries its refund's gateway.

  • credit_sourceobject | null

    Where a customer credit record came from. Always present; null on an order's records.

  • credit_source_payment_idstring | null

    ORDER_CREDIT_RECOVERY and ORDER_CREDIT_RESTORED only: the payment the credit was issued from.

  • customer_idstring | null

    Always null on an order's records.

  • customer_payment_funding_idstring | null

    Customer Portal payment rows and credit applied from one only: the customer payment it belongs to.

  • customer_payment_sourcesarray of objects

    Customer Portal rows only: the customer payments the money came from, each with customer_payment_funding_id, funding_transaction_id, amount (a decimal string) and currency_iso.

  • datestring (date-time) | null

    When it was recorded (the payment date you sent). ISO 8601 with offset, or null.

  • delete_blocked_reasonobject | null

    Recorded payments (ORDER_PAYMENT) and card payments only: why Delete a payment or refund refuses it, or null when it can be deleted. code is credit_issued_from_payment (with amount, a decimal string) or provider_payment_not_removable; message is the refusal's text.

    Child fields (3)

    • amountstring
    • codestring
    • messagestring
  • directionstring

    INCREASE (payments, payments from customer credit, REFUND_REVERSAL, ORDER_CREDIT_RECOVERY) or DECREASE (refunds and lost disputes, moves to customer credit, card voids, ORDER_CREDIT_RESTORED).

  • funding_payment_gatewaystring | null

    Customer Portal rows only: the provider (STRIPE, PAYPAL, SQUARE_V2, AUTHORIZE_NET, CHARGE_IT_PRO) or null.

  • has_open_holdboolean

    List and Get only, on STRIPE, PAYPAL and SQUARE_V2 card payments and Customer Portal payments: true while a dispute (or, for a Customer Portal payment, a review) is open.

  • is_deletableboolean

    false for card payments, Customer Portal payments, credit moves, card refunds, payments part of which moved to customer credit (and their refunds), refunds recorded against card payments, and the records YoPrint adds itself.

  • is_editableboolean

    true only for recorded payments (ORDER_PAYMENT).

  • negative_credit_amountinteger | number | string | null

    Card refunds only: credit issued from the payment that the customer had already spent and the refund took back anyway, leaving their credit negative (usually 0). 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.

  • order_idstring | null
  • payment_freeze_reasonstring | null

    List and Get only, on STRIPE, PAYPAL and SQUARE_V2 card payments and direct Customer Portal payments: chargeback_open or payment_under_review while refunds and credit moves are refused, otherwise null.

  • payment_gatewaystring | null

    The gateway (STRIPE, SQUARE_V2 and so on) for card payments and refunds; for a Customer Portal payment its provider (null when unknown), and CUSTOMER_CHECKOUT or CUSTOMER_CHECKOUT_CHARGEBACK on its refunds and lost disputes; null otherwise.

  • payment_gateway_sourcestring | null

    Card payments and refunds only: Square v2's source type (for example CARD), otherwise null.

  • payment_method_idstring | null

    Refunds take their payment's; null for card payments and credit moves.

  • payment_noticesarray of objects

    List and Get only, on the same payments as has_open_hold: one notice per open dispute.

    Fields of each item (10)

    • amountobject | null

      The disputed amount as a decimal pair with dp 3, or null when the payment covered several orders.

    • codestring

      dispute_open or dispute_under_review; on Customer Portal payments also payment_needs_attention.

    • currency_isostring
    • customer_payment_dispute_idstring
    • customer_payment_funding_idstring | null
    • deadline_atstring | null

      When the response to the provider is due (ISO 8601), or null.

    • next_actionstring

      For example respond_to_provider or awaiting_provider.

    • providerstring
    • provider_statusstring
    • stagestring | null
  • recovery_kindstring | null

    ORDER_CREDIT_RECOVERY and ORDER_CREDIT_RESTORED only: null on an order's records.

  • reference_descriptionstring | null
  • reference_idstring | null
  • refundable_amountinteger | number | string | null

    Payments only: the amount minus its refunds. Money moved to customer credit is not taken off here, though a refund can't include it. 0 for refunds, credit moves, payments from customer credit, and CHARGE_IT_PRO and SQUARE card payments. 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; for REFUND_REVERSAL, the payment; for ORDER_CREDIT_RECOVERY and ORDER_CREDIT_RESTORED, the refund; null otherwise.

  • remove_unavailableobject | null

    Recorded payments only: { "reason": "credit_issued", "amount": <thousandths> } when credit was issued from the payment, otherwise null.

  • restores_transaction_idstring | null

    ORDER_CREDIT_RESTORED only: the ORDER_CREDIT_RECOVERY record it gives back.

  • reversal_transaction_idstring | null

    Card refunds and ORDER_CREDIT_RESTORED only: the REFUND_REVERSAL record when the refund failed, or null.

  • reverses_transaction_idstring | null

    REFUND_REVERSAL only: the failed refund.

  • subtypestring

    PAYMENT, REFUND (also a lost dispute), TRANSFER (a customer credit move), ORDER_PAYMENT_VOIDED_NEG_ADJ (a voided card payment), REFUND_REVERSAL (a failed card refund given back to its payment), ORDER_CREDIT_RECOVERY (credit a refund took back) or ORDER_CREDIT_RESTORED (that credit given back when the refund failed).

  • tokenstring | null

    The gateway's charge token; null for recorded payments.

  • typestring

    MANUAL (recorded in YoPrint) or SYSTEM (card and Customer Portal payments and refunds, Shopify payments, adjustments).

  • user_idstring | null

    The team member who recorded it.

  • voidedboolean
• 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 can't see this order's finances or change it. This 403 has a short body, {"message": "No permission to change this order payment."}, with no success or error.

  Fix

  Ask the team owner for View Sales Order Pricing and permission to edit this order, or to be assigned to it.

• 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.

• 422Validation failed or the payment mutation was rejected by business rules.

  When

  Nothing paid, zero, an amount with decimals (validation_failed), too much (issue_credit_amount_above_available when a frozen payment holds the rest), or a draft order.

  Fix

  Check the order's payments first.

  When

  A payment is frozen by an open dispute or review (customer_payment_disputed_funds_unavailable or invoice_payment_funding_withheld, with error.reason).

  Fix

  Wait for the provider's decision, then try again.

Related

• PATCHMove all of an order's payments to customer credit/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/credit/refund_all_to_customer_credit
• POSTPay an order from the customer's credit/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/credit/pay_with_customer_credit

Example request

curl

curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/credit/refund_to_customer_credit' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "amount": 25000,    "reference_description": "Overpayment"  }'

Example response 200

Response

{
  "data": {
    "action": "ORDER_CREDIT_WITHDRAW",
    "amount": -25000,
    "credit_source": null,
    "customer_id": null,
    "date": "2026-11-03T09:00:00+00:00",
    "direction": "DECREASE",
    "id": "t0flTyfijq67bD",
    "is_deletable": false,
    "is_editable": false,
    "order_id": "V4keXwwxMQyXw7",
    "payment_gateway": null,
    "payment_method_id": null,
    "reference_description": "Overpayment",
    "reference_id": null,
    "refundable_amount": 0,
    "related_transaction": null,
    "subtype": "TRANSFER",
    "token": null,
    "type": "MANUAL",
    "user_id": "PydH0WtBhSeiNU",
    "voided": false
  },
  "status": 200,
  "success": true
}