# Create a payment link for a sales order

```http
POST https://secure.yoprint.com/v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment_link
```

- API version: v2
- Operation ID: `v2_public_sales_order_payment_link_create`
- Section: Invoices and payments › [Payment links](https://developer.yoprint.com/reference/payment-links.md)
- Web page: https://developer.yoprint.com/reference/payment-links/v2-sales-order-payment-link-create/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

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_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `hash_id` (string, required): 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

Content type `application/json`, required.

Fields:

- `unallocated_transactions` (array of objects, required): At least 1 item.
  - Each item:
    - `action` (string, required): Always `"create"`.
    - `invoice_id` (string, required): An invoice of this order.
    - `transaction_id` (string, required): A payment of this order, from the template.
    - `total` (decimal pair, optional): `{ "value": 1250, "dp": 2 }` is 12.50 (see https://developer.yoprint.com/concepts/money-and-quantities.md).
- `note` (string, optional)

### Example request

```bash
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"
      }
    ]
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (object, required): The payment link, as Get a payment link returns it.
  - `id` (string, required)
  - `order_id` (string, required)
  - `total` (decimal pair, required): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `allocated_transactions` (array of objects, optional): One entry per payment and invoice.
    - Each item:
      - `id` (string, optional)
      - `invoice_id` (string, optional)
      - `state` (string, optional): Always `existing`.
      - `total` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
      - `transaction_id` (string, optional): The payment's `id`.
      - `unallocated_amount` (decimal pair, optional): 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 https://developer.yoprint.com/concepts/money-and-quantities.md.
  - `created_at` (string (date-time) | null, optional): Created. ISO 8601 with offset, or null.
  - `note` (string | null, optional)
  - `updated_at` (string (date-time) | null, optional): Last changed. ISO 8601 with offset, or null.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "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
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You 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`.
- `404` Not 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.
- `422` Validation 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

- [Get what a new payment link can allocate](https://developer.yoprint.com/reference/payment-links/v2-sales-order-payment-link-get-create-template.md): `GET /v2/api/store/{team_slug}/v2/sales_order/{hash_id}/payment_link/get_create_template`
- [Update a payment link](https://developer.yoprint.com/reference/payment-links/v2-payment-link-update.md): `PUT /v2/api/store/{team_slug}/v2/payment_link/{hash_id}`
- [Show one payment link with allocations](https://developer.yoprint.com/reference/payment-links/v2-payment-link-show.md): `GET /v2/api/store/{team_slug}/v2/payment_link/{hash_id}`