Create a payment link for a sales order

POST/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment_link

v2Operation ID v2_public_sales_order_payment_link_create

A payment link (Allocations in the web app) records which invoices a payment pays: it splits payments received on the order across the order's invoices. It is not a link the customer pays through.

Allocates amounts of the order's payments to its invoices. Each entry in unallocated_transactions names a payment (transaction_id), an invoice of this order (invoice_id) and an amount (total.value, in thousandths: 12500 is 12.50; dp is ignored).

The answer is the payment link. {hash_id} is the order's id (for example V4keXwwxMQyXw7); the ord_ unique key is not accepted here.

Permission

Any member of the team.

Business rules

• Only published orders: otherwise 422 with the code "Action Not Allow".
• At least one entry, each with action: "create", transaction_id and invoice_id.
• Entries whose payment or invoice is not on this order are skipped. So is an entry whose invoice has nothing left to pay, or whose amount is more than the payment's unallocated amount; an amount above the invoice's balance is cut to that balance. The link is created even if every entry is skipped.
• total.value must be a whole number of thousandths (a fraction gives HTTP 500); without total the entry allocates 0.

Side effects

• Changes which invoices count as paid; refreshes the order for people who have it open in the web app.
• Updates the order's customer's balance totals in the background, and Customer Portal pages the customer has open refresh.

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.

• unallocated_transactionsarray of objectsrequired
  • At least 1 item
  Fields of each item (4)

  • actionstringrequired
    • Always "create"
  • invoice_idstringrequired

    An invoice of this order.

  • transaction_idstringrequired

    A payment of this order, from the template.

  • totaldecimal pair
    • { "value": 1250, "dp": 2 } is 12.50: value holds the digits, dp the decimal places. See Money and quantities.
• notestring

Response

200Successful response.

• dataobjectrequired

  The payment link, as Get a payment link returns it.

  Child fields (7)

  • idstringrequired
  • order_idstringrequired
  • totaldecimal pairrequired

    Total allocated. A decimal pair: the amount is value ÷ 10^dp ({ "value": 125000, "dp": 4 } is 12.50). Kept with 4 decimal places; an amount never set can come as { "value": 0, "dp": 0 }. Read dp every time: it can differ between fields and records.

    • See Money and quantities.
  • allocated_transactionsarray of objects

    One entry per payment and invoice.

    Fields of each item (6)

    • idstring
    • invoice_idstring
    • statestring

      Always existing.

    • totaldecimal pair

      Allocated to this invoice. A decimal pair: the amount is value ÷ 10^dp ({ "value": 50000, "dp": 3 } is 50.00). Fixed at 3 decimal places (dp 3). Read dp every time: it can differ between fields and records.

      • See Money and quantities.
    • transaction_idstring

      The payment's id.

    • unallocated_amountdecimal pair

      What the payment still has to allocate. A decimal pair: the amount is value ÷ 10^dp ({ "value": 50000, "dp": 3 } is 50.00). Fixed at 3 decimal places (dp 3). Read dp every time: it can differ between fields and records.

      • See Money and quantities.
  • created_atstring (date-time) | null

    Created. ISO 8601 with offset, or null.

  • notestring | null
  • updated_atstring (date-time) | null

    Last changed. ISO 8601 with offset, or null.

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

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

  When

  A draft order, or an entry without its ids.

  Fix

  Build the body from Get what a new payment link can allocate.

Related

• GETGet what a new payment link can allocate/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment_link/get_create_template
• PUTUpdate a payment link/v2/api/store/{team_slug}/v2/payment_link/{hash_id}
• GETShow one payment link with allocations/v2/api/store/{team_slug}/v2/payment_link/{hash_id}

Example request

curl

curl -X POST 'https://secure.yoprint.com/v2/api/store/your-team/v2/sales_order/V4keXwwxMQyXw7/payment_link' \  -H 'Authorization: Bearer YOUR_API_KEY' \  -H 'Accept: application/json' \  -H 'X-Yoprint-Decimal-Format: exact-v1' \  -H 'Content-Type: application/json' \  -d '{    "note": "Split deposit",    "unallocated_transactions": [      {        "action": "create",        "invoice_id": "QRbvVd2ZKcvSTB",        "total": {          "dp": 3,          "value": 50000        },        "transaction_id": "hAwWd7vPrqjuHD"      }    ]  }'

Example response 200

Response

{
  "data": {
    "allocated_transactions": [
      {
        "id": "I9uyv9BtQiReQ6",
        "invoice_id": "QRbvVd2ZKcvSTB",
        "state": "existing",
        "total": {
          "dp": 3,
          "value": 50000
        },
        "transaction_id": "hAwWd7vPrqjuHD",
        "unallocated_amount": {
          "dp": 3,
          "value": 0
        }
      }
    ],
    "created_at": "2026-11-03T09:00:00+00:00",
    "id": "SmIWUp2A3mG3bA",
    "note": "Split deposit",
    "order_id": "V4keXwwxMQyXw7",
    "total": {
      "dp": 4,
      "value": 500000
    },
    "updated_at": "2026-11-03T09:00:00+00:00"
  },
  "status": 200,
  "success": true
}