Payment links

A payment link is a reusable URL. Each buyer who opens it gets a new checkout session and a new transaction. Times on payment links are epoch milliseconds.

Read Payment links for the model and the lifecycle. For a walkthrough, read Sell with payment links.

The payment link object#

A reusable link that creates a checkout session for each buyer. Times are epoch milliseconds.

Attributes

idstring
objectTypestring
accountIdstring
titlestring
The title of the link.
descriptionstringCan be absent
amountSourceobject
Exactly one amount source. mode selects the source. Fields of another source are refused. All money is in minor units.
Child attributes of amountSource
- modestring
  catalog_items sells catalog prices, fixed_amount sells one amount, and buyer_entered_amount lets the buyer choose within a range.
  One of: catalog_items, fixed_amount, buyer_entered_amount
- currencystring
  An ISO 4217 alphabetic currency code.
  Pattern ^[A-Z]{3}$.
- lineItemsarray of objectsCan be absent
  The catalog prices and quantities of a catalog_items source.
  At most 100 items.
  Child attributes of lineItems
  priceIdstring
  A catalog price of one of your products.
  quantityintegerCan be absent
  1 to 999. Default 1.
- allowQuantityEditsbooleanCan be absent
  Lets the buyer change the quantity of a catalog_items source.
  Default false.
- amountMinorintegerCan be absent
  The amount of a fixed_amount source.
  At least 1.
- minimumAmountMinorintegerCan be absent
  The lowest accepted amount of a buyer_entered_amount source.
  At least 1.
- maximumAmountMinorintegerCan be absent
  The highest accepted amount, when a limit exists.
  At least 1.
- suggestedAmountsMinorarray of integersCan be absent
  Suggested amounts. Each must be positive and within the range.
urlstring (URL)
The buyer-facing link on the checkout host.
successUrlstring (URL)
cancelUrlstring (URL)
usageLimitintegerCan be absent
usageCountinteger
How many sessions the link has created.
activeboolean
expiresAtintegerCan be absent
createdAtinteger

The response can include fields that this page does not list. Ignore fields that you do not know.

The payment link object

{
  "id": "plink_4Tn8QmW1vX6kB3zLc",
  "objectType": "payment_link",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "title": "Team plan, annual",
  "active": true,
  "url": "https://checkout.merxian.com/sandbox/l/plink_4Tn8QmW1vX6kB3zLc",
  "amountSource": {
    "mode": "catalog_items",
    "currency": "EUR",
    "lineItems": [
      {
        "priceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 1
      }
    ],
    "allowQuantityEdits": false
  },
  "successUrl": "https://shop.example.com/thanks",
  "cancelUrl": "https://shop.example.com/pricing",
  "usageCount": 12,
  "createdAt": 1789377667000
}

Create a payment link#

POST/v1/payment-links

Creates an active payment link. Each time a buyer opens the link, Merxian creates a new checkout session and a new draft transaction.

A link has exactly one amount source: catalog items, a fixed amount, or an amount that the buyer enters.

Requires the checkout:write scope.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Request body

titlestringRequired
The title of the link.
At least 1 character.
descriptionstring
amountSourceobjectRequired
Exactly one amount source. mode selects the source. Fields of another source are refused. All money is in minor units.
Child attributes of amountSource
- modestringRequired
  catalog_items sells catalog prices, fixed_amount sells one amount, and buyer_entered_amount lets the buyer choose within a range.
  One of: catalog_items, fixed_amount, buyer_entered_amount
- currencystringRequired
  An ISO 4217 alphabetic currency code.
  Pattern ^[A-Z]{3}$.
- lineItemsarray of objects
  The catalog prices and quantities of a catalog_items source.
  At most 100 items.
  Child attributes of lineItems
  priceIdstringRequired
  A catalog price of one of your products.
  quantityinteger
  1 to 999. Default 1.
- allowQuantityEditsboolean
  Lets the buyer change the quantity of a catalog_items source.
  Default false.
- amountMinorinteger
  The amount of a fixed_amount source.
  At least 1.
- minimumAmountMinorinteger
  The lowest accepted amount of a buyer_entered_amount source.
  At least 1.
- maximumAmountMinorinteger
  The highest accepted amount, when a limit exists.
  At least 1.
- suggestedAmountsMinorarray of integers
  Suggested amounts. Each must be positive and within the range.
successUrlstring (URL)Required
Must be https, except for a localhost URL in local development.
At most 2048 characters.
cancelUrlstring (URL)Required
At most 2048 characters.
usageLimitinteger
How many sessions the link may create. No limit when absent.
At least 1.
expiresAtinteger
When the link stops working, in epoch milliseconds. Must be in the future.

Returns

201The payment link object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

POST /v1/payment-links

curl -X POST "https://api.merxian.com/v1/payment-links" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Team plan, annual",
    "amountSource": {
      "mode": "catalog_items",
      "currency": "EUR",
      "lineItems": [
        {
          "priceId": "price_4Wm9TqLz2Xb7KdN8r",
          "quantity": 1
        }
      ]
    },
    "successUrl": "https://shop.example.com/thanks",
    "cancelUrl": "https://shop.example.com/pricing"
  }'

const response = await fetch('https://api.merxian.com/v1/payment-links', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "title": "Team plan, annual",
    "amountSource": {
      "mode": "catalog_items",
      "currency": "EUR",
      "lineItems": [
        {
          "priceId": "price_4Wm9TqLz2Xb7KdN8r",
          "quantity": 1
        }
      ]
    },
    "successUrl": "https://shop.example.com/thanks",
    "cancelUrl": "https://shop.example.com/pricing"
  }),
})
const result = await response.json()

Response · 201

{
  "id": "plink_4Tn8QmW1vX6kB3zLc",
  "objectType": "payment_link",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "title": "Team plan, annual",
  "active": true,
  "url": "https://checkout.merxian.com/sandbox/l/plink_4Tn8QmW1vX6kB3zLc",
  "amountSource": {
    "mode": "catalog_items",
    "currency": "EUR",
    "lineItems": [
      {
        "priceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 1
      }
    ],
    "allowQuantityEdits": false
  },
  "successUrl": "https://shop.example.com/thanks",
  "cancelUrl": "https://shop.example.com/pricing",
  "usageCount": 0,
  "createdAt": 1789377667000
}

Retrieve a payment link#

GET/v1/payment-links/{paymentLinkId}

Requires the checkout:read scope.

Path parameters

paymentLinkIdstringRequired
The payment link id.

Returns

200The payment link object.

Errors

Status	Meaning
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

GET /v1/payment-links/{paymentLinkId}

curl "https://api.merxian.com/v1/payment-links/plink_4Tn8QmW1vX6kB3zLc" \
  -H "Authorization: Bearer $MERXIAN_API_KEY"

const response = await fetch('https://api.merxian.com/v1/payment-links/plink_4Tn8QmW1vX6kB3zLc', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
  },
})
const result = await response.json()

Response · 200

{
  "id": "plink_4Tn8QmW1vX6kB3zLc",
  "objectType": "payment_link",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "title": "Team plan, annual",
  "active": true,
  "url": "https://checkout.merxian.com/sandbox/l/plink_4Tn8QmW1vX6kB3zLc",
  "amountSource": {
    "mode": "catalog_items",
    "currency": "EUR",
    "lineItems": [
      {
        "priceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 1
      }
    ],
    "allowQuantityEdits": false
  },
  "successUrl": "https://shop.example.com/thanks",
  "cancelUrl": "https://shop.example.com/pricing",
  "usageCount": 12,
  "createdAt": 1789377667000
}

List payment links#

GET/v1/payment-links

Returns one page of your payment links, newest first.

Requires the checkout:read scope.

Query parameters

limitinteger
How many links to return. A value outside 1-100 fails with 400.
1 to 100. Default 20.
cursorstring
An opaque cursor taken from a previous response's pagination.nextCursor.

Returns

200A page of payment link objects, in data, with pagination.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

GET /v1/payment-links

curl "https://api.merxian.com/v1/payment-links?limit=20" \
  -H "Authorization: Bearer $MERXIAN_API_KEY"

const response = await fetch('https://api.merxian.com/v1/payment-links?limit=20', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
  },
})
const result = await response.json()

Response · 200

{
  "data": [
    {
      "id": "plink_4Tn8QmW1vX6kB3zLc",
      "objectType": "payment_link",
      "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
      "title": "Team plan, annual",
      "active": true,
      "url": "https://checkout.merxian.com/sandbox/l/plink_4Tn8QmW1vX6kB3zLc",
      "amountSource": {
        "mode": "catalog_items",
        "currency": "EUR",
        "lineItems": [
          {
            "priceId": "price_4Wm9TqLz2Xb7KdN8r",
            "quantity": 1
          }
        ],
        "allowQuantityEdits": false
      },
      "successUrl": "https://shop.example.com/thanks",
      "cancelUrl": "https://shop.example.com/pricing",
      "usageCount": 12,
      "createdAt": 1789377667000
    }
  ],
  "pagination": {
    "nextCursor": "eyJpZCI6InR4bl8wRjhtUTJyWGJUNGtMOXBaYSJ9"
  }
}

Update a payment link#

PATCH/v1/payment-links/{paymentLinkId}

Changes the fields that you send and keeps the others. An absent or null field keeps its value, so you cannot clear a field. An amountSource replaces the full amount source and must be complete.

Requires the checkout:write scope.

Path parameters

paymentLinkIdstringRequired
The payment link id.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Request body

titlestring
descriptionstring
amountSourceobject
Exactly one amount source. mode selects the source. Fields of another source are refused. All money is in minor units.
Child attributes of amountSource
- modestringRequired
  catalog_items sells catalog prices, fixed_amount sells one amount, and buyer_entered_amount lets the buyer choose within a range.
  One of: catalog_items, fixed_amount, buyer_entered_amount
- currencystringRequired
  An ISO 4217 alphabetic currency code.
  Pattern ^[A-Z]{3}$.
- lineItemsarray of objects
  The catalog prices and quantities of a catalog_items source.
  At most 100 items.
  Child attributes of lineItems
  priceIdstringRequired
  A catalog price of one of your products.
  quantityinteger
  1 to 999. Default 1.
- allowQuantityEditsboolean
  Lets the buyer change the quantity of a catalog_items source.
  Default false.
- amountMinorinteger
  The amount of a fixed_amount source.
  At least 1.
- minimumAmountMinorinteger
  The lowest accepted amount of a buyer_entered_amount source.
  At least 1.
- maximumAmountMinorinteger
  The highest accepted amount, when a limit exists.
  At least 1.
- suggestedAmountsMinorarray of integers
  Suggested amounts. Each must be positive and within the range.
successUrlstring (URL)
At most 2048 characters.
cancelUrlstring (URL)
At most 2048 characters.
usageLimitinteger
At least 1.
activeboolean
expiresAtinteger
Epoch milliseconds.

Returns

200The payment link object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
409	The request conflicts with the current state of the resource, or the idempotency key was used with a different request.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

PATCH /v1/payment-links/{paymentLinkId}

curl -X PATCH "https://api.merxian.com/v1/payment-links/plink_4Tn8QmW1vX6kB3zLc" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Team plan, annual (2027)",
    "usageLimit": 100
  }'

const response = await fetch('https://api.merxian.com/v1/payment-links/plink_4Tn8QmW1vX6kB3zLc', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "title": "Team plan, annual (2027)",
    "usageLimit": 100
  }),
})
const result = await response.json()

Response · 200

{
  "id": "plink_4Tn8QmW1vX6kB3zLc",
  "objectType": "payment_link",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "title": "Team plan, annual (2027)",
  "active": true,
  "url": "https://checkout.merxian.com/sandbox/l/plink_4Tn8QmW1vX6kB3zLc",
  "amountSource": {
    "mode": "catalog_items",
    "currency": "EUR",
    "lineItems": [
      {
        "priceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 1
      }
    ],
    "allowQuantityEdits": false
  },
  "successUrl": "https://shop.example.com/thanks",
  "cancelUrl": "https://shop.example.com/pricing",
  "usageCount": 12,
  "createdAt": 1789377667000,
  "usageLimit": 100
}

Activate a payment link#

POST/v1/payment-links/{paymentLinkId}/activate

Lets the link create checkout sessions again.

Requires the checkout:write scope.

Path parameters

paymentLinkIdstringRequired
The payment link id.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Returns

200The payment link object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

POST /v1/payment-links/{paymentLinkId}/activate

curl -X POST "https://api.merxian.com/v1/payment-links/plink_4Tn8QmW1vX6kB3zLc/activate" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b"

const response = await fetch('https://api.merxian.com/v1/payment-links/plink_4Tn8QmW1vX6kB3zLc/activate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
})
const result = await response.json()

Response · 200

{
  "id": "plink_4Tn8QmW1vX6kB3zLc",
  "objectType": "payment_link",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "title": "Team plan, annual",
  "active": true,
  "url": "https://checkout.merxian.com/sandbox/l/plink_4Tn8QmW1vX6kB3zLc",
  "amountSource": {
    "mode": "catalog_items",
    "currency": "EUR",
    "lineItems": [
      {
        "priceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 1
      }
    ],
    "allowQuantityEdits": false
  },
  "successUrl": "https://shop.example.com/thanks",
  "cancelUrl": "https://shop.example.com/pricing",
  "usageCount": 12,
  "createdAt": 1789377667000
}

Deactivate a payment link#

POST/v1/payment-links/{paymentLinkId}/deactivate

Stops the link from creating checkout sessions. Sessions that the link already created stay usable.

Requires the checkout:write scope.

Path parameters

paymentLinkIdstringRequired
The payment link id.

Headers

Idempotency-KeystringRequired
A unique key for this request, at most 200 characters. A retry with the same key and body returns the first result.
At most 200 characters.

Returns

200The payment link object.

Errors

Status	Meaning
400	The request is not valid. See the error body for the field at fault.
401	The API key is missing, malformed, revoked, or unknown.
403	The API key does not hold the scope that this operation requires.
404	The resource does not exist, or it belongs to another account.
500	An unexpected error occurred. Retry with the same idempotency key.
502	Merxian could not complete the request. Retry with the same idempotency key.
503	Merxian could not verify the API key. Retry later.

The error reference lists the codes in each error body.

POST /v1/payment-links/{paymentLinkId}/deactivate

curl -X POST "https://api.merxian.com/v1/payment-links/plink_4Tn8QmW1vX6kB3zLc/deactivate" \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b"

const response = await fetch('https://api.merxian.com/v1/payment-links/plink_4Tn8QmW1vX6kB3zLc/deactivate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.MERXIAN_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
  },
})
const result = await response.json()

Response · 200

{
  "id": "plink_4Tn8QmW1vX6kB3zLc",
  "objectType": "payment_link",
  "accountId": "acct_5Rn8bQ2xW7mK4tLzP",
  "title": "Team plan, annual",
  "active": false,
  "url": "https://checkout.merxian.com/sandbox/l/plink_4Tn8QmW1vX6kB3zLc",
  "amountSource": {
    "mode": "catalog_items",
    "currency": "EUR",
    "lineItems": [
      {
        "priceId": "price_4Wm9TqLz2Xb7KdN8r",
        "quantity": 1
      }
    ],
    "allowQuantityEdits": false
  },
  "successUrl": "https://shop.example.com/thanks",
  "cancelUrl": "https://shop.example.com/pricing",
  "usageCount": 12,
  "createdAt": 1789377667000
}