Skip to content
YoPrintDevelopers

Get the starting point for editing a payment link

Open .md

GET/v2/api/store/{team_slug}/v2/payment_link/{hash_id}/get_update_template

v2Operation ID v2_public_payment_link_get_update_template

Returns what you need to build an Update a payment link body: the link with its allocated_transactions (state existing, each with its allocation id), plus unallocated_transactions: every payment on the order that still has money to allocate (state new, transaction_id, unallocated_amount, invoice_id null and a zero total).

To edit: change total on existing rows and mark them update or delete; fill invoice_id and total on new rows and mark them create. Amounts in allocations must use exactly 3 decimal places (dp: 3):

  • Correct: { "value": 12500, "dp": 3 } for 12.50.
  • Wrong: { "value": 1250, "dp": 2 } — the server always interprets value as thousandths (scale 3), which would mean 1.250, and validation requires dp: 3.

In answers, the link's own total uses 4 decimal places ({ "value": 175000, "dp": 4 } is 17.50): always read each pair's dp.

Permission

Any member of the team. No sales order permission is checked.

Path parameters

  • team_slugstringrequired

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

    • Example your-team
  • hash_idstringrequired

    The payment link's hash id. Hash ids only: a unique key or a document number gives 404.

    • Example IirNDCwiaCVSKx

Request body

This operation takes no request body.

Response

200Successful response.

  • dataobjectrequired
    Child fields (8)
    • allocated_transactionsarray of objectsrequired

      One row per allocation.

      Fields of each item (6)
      • statestring
        • Always "existing"
      • idstring

        The allocation. Send it in allocated_transactions[].id to update or delete it.

      • invoice_idstring

        The invoice it pays.

      • totaldecimal pair

        The allocated amount (usually 3 decimal places; a finer stored amount comes back with a larger dp). A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

      • transaction_idstring

        The payment.

      • unallocated_amountdecimal pair

        What the payment still has to allocate (usually 3 decimal places; a finer stored amount comes back with a larger dp). A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

    • created_atstring (date-time)required
    • idstringrequired

      The payment link.

    • order_idstringrequired

      The sales order.

    • totaldecimal pairrequired

      The sum of its allocations. A decimal pair: the amount is value ÷ 10^dp ({ "value": 175000, "dp": 4 } is 17.50). Kept at 4 decimal places; { "value": 0, "dp": 0 } when the link has no allocations. Read dp every time.

    • updated_atstring (date-time)required
    • notestring | null
    • unallocated_transactionsarray of objects

      Payments on the order that still have money to allocate.

      Fields of each item (5)
      • statestring
        • Always "new"
      • invoice_idnull

        Fill in the invoice to allocate to.

      • totaldecimal pair

        Starts at { "value": 0, "dp": 3 }: fill in the amount. A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

      • transaction_idstring

        A payment with money left to allocate.

      • unallocated_amountdecimal pair

        What it has left (usually 3 decimal places; a finer stored amount comes back with a larger dp). A decimal pair: the amount is value ÷ 10^dp ({ "value": 1250, "dp": 2 } is 12.50). Read dp every time: it can differ between fields and records.

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

  • 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
    The link isn't your team's.
    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
    The order came from Shopify and was deleted there (shopify_order_deleted_externally).
    Fix
    Only local cleanup is allowed on that order.

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 specSupport: support@yoprint.comyoprint.com